@telorun/sdk 0.48.0 → 0.50.0

package/src/log-sink.ts

@@ -0,0 +1,115 @@
+import type { LogRecord } from "./log-record.js";
+
+/**
+ * The `Telo.Sink` capability contract — `kernel/specs/logging.md` §10.
+ *
+ * This lives in the SDK rather than the kernel because §10.2 makes the sink set
+ * **open to the ecosystem**: a third party ships a sink by publishing a module
+ * whose kind extends `Telo.LogSink`. That module is an ordinary module author's
+ * artifact, so the contract it implements belongs on the module-author surface,
+ * not behind a kernel-internal import.
+ *
+ * The logger writes to a sink through this contract directly and **never**
+ * through `ctx.invoke`: per-record dispatch is far too slow for a logging hot
+ * path, and the dispatch chokepoint emits trace events, so logging through it
+ * would generate telemetry from inside the telemetry path.
+ *
+ * The contract is deliberately payload-opaque — no filtering, no encoding —
+ * which is what lets a future `Telo.TraceSink` reuse the capability with a
+ * different record type. Log-specific configuration lives on the
+ * `Telo.LogSink` abstract instead.
+ */
+
+export type DropCause = "buffer_full" | "sampled" | "encode_failure" | "sink_error";
+
+/** Policy for a saturated buffer (§10.3). A runtime that cannot honour `block`
+ *  rejects the manifest at load rather than silently substituting a dropping
+ *  policy. */
+export type OnFull = "block" | "drop_new" | "drop_old";
+
+export interface SinkBufferPolicy {
+  /** Bounded. Never unbounded. */
+  buffer: number;
+  onFull: OnFull;
+  /** Max time a record may sit buffered, in milliseconds. */
+  flushIntervalMs: number;
+}
+
+export const DEFAULT_BUFFER_POLICY: SinkBufferPolicy = {
+  buffer: 8192,
+  onFull: "drop_new",
+  flushIntervalMs: 1000,
+};
+
+export interface LogSinkInstance {
+  /** Identity for drop accounting (§10.4): the resource name for a `!ref`, or
+   *  kind plus position for an inline definition. */
+  readonly sinkId: string;
+
+  /** This sink's own fan-out filter, applied *after* the record is created. It
+   *  never decides whether a record is created at all — that is the pipeline's
+   *  minimum-level gate. */
+  readonly level: number;
+
+  /**
+   * Whether the sink can be drained to its destination from inside a
+   * synchronous call, with no scheduler turn. A file descriptor write can; a
+   * network round-trip cannot, and neither can a transport living on another
+   * thread — the producer cannot drain a queue it does not own.
+   *
+   * A capability tier, not a language carve-out: the same rule makes an OTLP
+   * sink best-effort in Rust and Go, where blocking a producer thread is
+   * possible but still would not make a round-trip synchronous.
+   */
+  readonly syncFlushable: boolean;
+
+  /** Accept a record. MUST NOT throw — a sink failure is reported out-of-band
+   *  and counted, never propagated to the caller (§8.4). */
+  write(record: LogRecord): void;
+
+  /** Drain asynchronously. */
+  flush(): Promise<void>;
+
+  /** Drain to completion before returning. A no-op when {@link syncFlushable}
+   *  is `false`; the `fatal` path initiates those sinks' flushes without
+   *  waiting, because blocking on a sink it cannot synchronously drain is a
+   *  deadlock on an event loop, not durability. */
+  flushSync(): void;
+
+  /** Release the destination. Called during teardown, after the final flush. */
+  close(): Promise<void>;
+}
+
+/**
+ * The pipeline surface a sink controller reaches for — attach, detach, resolve a
+ * level, count a drop. Deliberately narrow: everything else about the pipeline
+ * stays private to the runtime, so a third-party sink depends on this and
+ * nothing deeper.
+ */
+export interface LoggingHost {
+  attach(sink: LogSinkInstance): void;
+  detach(sink: LogSinkInstance): void;
+  /** Resolve a sink's declared `level:` to a severity number, falling back to
+   *  the effective scope threshold when the sink declares none (§12.1). */
+  levelFor(level: string | undefined): number;
+  /** Count `count` dropped records against this sink so §10.4's accounting stays
+   *  complete. `count` defaults to 1; a sink that loses a whole batch at once
+   *  (an OTLP export failure) passes the batch size so the total is not
+   *  undercounted to one-per-failure. */
+  recordDrop(sinkId: string, cause: DropCause, count?: number): void;
+}
+
+/** The diagnostic §10.3 requires when a runtime cannot honour `on_full: block`.
+ *  Rejecting is deliberate: `on_full` exists so an operator can state durability
+ *  intent, and silently substituting a dropping policy hands back the opposite
+ *  guarantee — discovered from a gap in an audit trail rather than from an
+ *  error. */
+export function blockUnsupportedMessage(sinkId: string): string {
+  return (
+    `Sink "${sinkId}": on_full: block is not supported by this runtime ` +
+    `(single-threaded event loop — blocking the producer would stall the writer). ` +
+    `Use \`drop_new\` or \`drop_old\`, or move this sink to a worker thread.`
+  );
+}
+
+export const BLOCK_UNSUPPORTED = "ERR_LOG_SINK_ON_FULL_UNSUPPORTED";

package/src/logger.ts

@@ -0,0 +1,125 @@
+import type { AnyValue, LogAttributes } from "./log-record.js";
+import type { SeverityNumber } from "./log-severity.js";
+
+/**
+ * The logger surface every Telo runtime exposes — `kernel/specs/logging.md` §8.
+ *
+ * Reached ambiently as `ctx.log`. The logger is ambient rather than a resource
+ * because it must work before any resource initializes; its *sinks* are
+ * resources, which is what keeps the destination set open to the ecosystem.
+ */
+
+/**
+ * A value resolved only on the emit path (§8.2) — slog's `LogValuer`, zap's
+ * `ObjectMarshaler`, `tracing`'s `Value`. A deferred value attached to a
+ * suppressed record is never resolved, so an expensive rendering costs nothing
+ * below the threshold. This is RECOMMENDED sugar and does **not** substitute for
+ * {@link Logger.enabled}, which is the only mechanism that avoids evaluating a
+ * call's *arguments*.
+ */
+export interface LogValuer {
+  toLogValue(): AnyValue;
+}
+
+export type LogAttributeInput = AnyValue | LogValuer;
+export type LogAttributesInput = Record<string, LogAttributeInput>;
+
+/** Per-record extras that are top-level record fields rather than attributes.
+ *  Kept out of the attribute map so they cannot collide with a reserved key. */
+export interface LogOptions {
+  /** Any thrown value. Normalized to the record's `error` (§4.2), with the
+   *  `cause` chain bounded per §6.3. */
+  error?: unknown;
+  /** Identifies a class of event; max 256 chars. Bridges to the event bus. */
+  eventName?: string;
+  /** When the event occurred, if earlier than the moment `log()` was called —
+   *  set by a bridge, which also stamps `observedTimestamp` (§13.3). */
+  timestamp?: bigint;
+  /** The original source spelling of the level, preserved when bridging a level
+   *  Telo does not name (§5.1). Defaults to the canonical short name. */
+  severityText?: string;
+}
+
+export interface Logger {
+  /**
+   * Whether a record at this severity would reach any sink. The load-bearing
+   * performance primitive: guard an expensive call with it so the *arguments*
+   * are never evaluated.
+   *
+   * Never blocks, never throws. The result is **not static** — it changes when
+   * configuration changes or a sink attaches or detaches (§12.4), so callers
+   * re-check per emission rather than caching a boolean.
+   */
+  enabled(severity: SeverityNumber): boolean;
+
+  /**
+   * Emit a record. Never throws, under any condition, including sink failure —
+   * a sink failure is reported on the fallback diagnostic stream and counted,
+   * never propagated and never swallowed (§8.4).
+   */
+  log(
+    severity: SeverityNumber,
+    message: string,
+    attributes?: LogAttributesInput,
+    options?: LogOptions,
+  ): void;
+
+  /**
+   * A child logger whose bound attributes are merged into every record it emits.
+   * Record attributes override bound attributes. Binding is O(1) amortized: the
+   * merge happens once here, never per record.
+   */
+  with(attributes: LogAttributesInput): Logger;
+
+  /** Drain every attached sink. Bounded by the caller; see §10.5. */
+  flush(): Promise<void>;
+
+  trace(message: string, attributes?: LogAttributesInput, options?: LogOptions): void;
+  debug(message: string, attributes?: LogAttributesInput, options?: LogOptions): void;
+  info(message: string, attributes?: LogAttributesInput, options?: LogOptions): void;
+  warn(message: string, attributes?: LogAttributesInput, options?: LogOptions): void;
+  error(message: string, attributes?: LogAttributesInput, options?: LogOptions): void;
+  /**
+   * Emits at severity 21. Severity never implies control flow (§5, D5): `fatal`
+   * does **not** terminate the process, exit, or panic — it triggers an
+   * immediate flush, synchronous on every sink that supports it and best-effort
+   * on the rest (§10.5).
+   */
+  fatal(message: string, attributes?: LogAttributesInput, options?: LogOptions): void;
+}
+
+/** Resolve a {@link LogValuer} if the value is one, else pass it through. */
+export function isLogValuer(value: unknown): value is LogValuer {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as LogValuer).toLogValue === "function"
+  );
+}
+
+/** A logger that discards everything. Used where a logger is structurally
+ *  required before one is available, and by tests that assert silence. */
+export const NOOP_LOGGER: Logger = {
+  enabled: () => false,
+  log: () => {},
+  with: () => NOOP_LOGGER,
+  flush: async () => {},
+  trace: () => {},
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  fatal: () => {},
+};
+
+/** The bound-attribute merge of {@link Logger.with}, exposed so a runtime's
+ *  child-logger implementation and its conformance vectors share one definition
+ *  of "record attributes win". */
+export function mergeBoundAttributes(
+  bound: LogAttributes | undefined,
+  record: LogAttributes | undefined,
+): LogAttributes | undefined {
+  if (!bound) return record;
+  if (!record) return bound;
+  return { ...bound, ...record };
+}

package/src/network-fetch.ts

@@ -0,0 +1,175 @@
+import { isCancellationError } from "./cancellation.js";
+import { InvokeError } from "./invoke-error.js";
+
+/** Raised when a request never reached the peer — DNS, connect, reset, or TLS
+ *  trust. Distinct from a non-OK HTTP response, which is a reply the caller
+ *  interprets itself. */
+export const ERR_NETWORK_UNREACHABLE = "ERR_NETWORK_UNREACHABLE";
+
+/** The facts a transport failure carries. Deliberately structured rather than
+ *  pre-rendered: a controller reports *what happened*, and whoever displays the
+ *  error turns it into a sentence. Prose baked into a controller would have to
+ *  be re-typed identically by every language SDK (TS, Rust, Go, …) and would
+ *  drift; `cause: "ENOTFOUND"` is the same symbol in every language.
+ *
+ *  `message` on the thrown error is a reasonable default for today's renderers;
+ *  a kernel-side renderer can format from these fields instead. */
+export interface NetworkErrorData {
+  /** What was being attempted, e.g. `"Embedding model request"`. */
+  operation: string;
+  url: string;
+  host: string;
+  port?: number;
+  /** The OS/undici code — `ENOTFOUND`, `ECONNREFUSED`, `CERT_HAS_EXPIRED`, … */
+  cause: string;
+  /** The underlying error's own message, kept verbatim. Carries detail no code
+   *  mapping has (`SSL alert number 80`, a resolver's remarks), so wrapping is
+   *  never a downgrade on an unmapped code. */
+  detail?: string;
+  /** `metadata.name` of the resource whose configuration produced `url`, so the
+   *  error names the actual instance rather than its kind. */
+  resource?: string;
+  /** The setting to change — a manifest field (`baseUrl`) or a CLI/env name
+   *  (`--registry`). Structured rather than a pre-written sentence: this is the
+   *  one genuinely actionable part, and prose here would be the thing every
+   *  other language SDK has to retype and keep in sync. */
+  setting?: string;
+}
+
+/** Human explanation per transport failure code. Interpolates only the facts
+ *  already in `NetworkErrorData`, so a renderer in another language can produce
+ *  the same sentence from the same fields. */
+function explain(code: string, host: string, port?: number): string {
+  const target = port ? `${host}:${port}` : host;
+  switch (code) {
+    case "ENOTFOUND":
+      return `DNS lookup failed for host '${host}' — the name does not resolve`;
+    case "EAI_AGAIN":
+      return `DNS is temporarily unavailable resolving '${host}' — a transient resolver failure`;
+    case "ECONNREFUSED":
+      return `nothing is listening on ${target}`;
+    case "ECONNRESET":
+      return `the connection to ${target} was reset by the peer`;
+    case "EHOSTUNREACH":
+      return `no network route to ${host}`;
+    case "ETIMEDOUT":
+    case "UND_ERR_CONNECT_TIMEOUT":
+      return `the connection to ${target} timed out`;
+    case "CERT_HAS_EXPIRED":
+      return `the TLS certificate presented by ${host} has expired`;
+    case "DEPTH_ZERO_SELF_SIGNED_CERT":
+    case "SELF_SIGNED_CERT_IN_CHAIN":
+      return `the TLS certificate presented by ${host} is self-signed and not trusted`;
+    case "UNABLE_TO_VERIFY_LEAF_SIGNATURE":
+      return `the TLS certificate chain presented by ${host} could not be verified`;
+    case "EPROTO":
+      return `the TLS handshake with ${host} failed`;
+    default:
+      return `the request to ${target} failed at the transport layer`;
+  }
+}
+
+/** The deepest `message` in the cause chain — the one carrying detail a code
+ *  mapping cannot have. Skips undici's own `"fetch failed"`, which is the
+ *  placeholder this whole module exists to replace. */
+function causeDetail(err: unknown): string | undefined {
+  let current: unknown = err;
+  let detail: string | undefined;
+  for (let depth = 0; current && depth < 5; depth++) {
+    const message = (current as { message?: unknown }).message;
+    if (typeof message === "string" && message && message !== "fetch failed") detail = message;
+    current = (current as { cause?: unknown }).cause;
+  }
+  return detail;
+}
+
+/**
+ * Walk the cause chain for the first `code` — undici wraps the real error one or
+ * more levels down, which is exactly the detail lost when only `message` is
+ * reported.
+ *
+ * Exported because classifying a network failure by substring-matching the
+ * message does not work: `fetch` rejects with the literal text `"fetch failed"`
+ * for DNS, refusal, and TLS alike, so a `message.includes("enotfound")` test
+ * silently never matches and every failure collapses into whichever branch is
+ * last. Callers with their own error contract should classify on this code
+ * rather than on prose.
+ */
+export function networkCauseCode(err: unknown): string | undefined {
+  let current: unknown = err;
+  for (let depth = 0; current && depth < 5; depth++) {
+    const code = (current as { code?: unknown }).code;
+    if (typeof code === "string") return code;
+    current = (current as { cause?: unknown }).cause;
+  }
+  return undefined;
+}
+
+/**
+ * `fetch` that turns a transport-level failure into an {@link InvokeError}
+ * carrying {@link NetworkErrorData}, instead of undici's opaque
+ * `TypeError: fetch failed` whose real cause sits unread on `error.cause`.
+ *
+ * Only *transport* failures are wrapped. A non-OK response is returned
+ * untouched, because a status code is a reply the caller interprets (and often
+ * renders from the provider's own error body) — so this drops into an existing
+ * call site without changing status handling. Cancellation is re-thrown as-is:
+ * an aborted request is the caller's intent, not a network fault.
+ *
+ * @param context.operation What is being attempted, for the message.
+ * @param context.resource `metadata.name` of the resource whose configuration
+ *   produced the URL, so the error names the instance, not just its kind.
+ * @param context.setting The manifest field or CLI/env name to change. Passed
+ *   as a bare identifier, never a sentence — the wording is composed here, in
+ *   one place, so another language's SDK supplies the same two facts rather
+ *   than retyping the same English.
+ */
+export async function fetchOrThrow(
+  input: string | URL,
+  init: RequestInit | undefined,
+  context: { operation: string; resource?: string; setting?: string },
+): Promise<Response> {
+  const url = typeof input === "string" ? input : input.toString();
+  try {
+    return await fetch(input, init);
+  } catch (err) {
+    if (isCancellationError(err)) throw err;
+    if (err instanceof DOMException && err.name === "AbortError") throw err;
+
+    const code = networkCauseCode(err) ?? "UNKNOWN";
+    let host = url;
+    let port: number | undefined;
+    try {
+      const parsed = new URL(url);
+      host = parsed.hostname;
+      if (parsed.port) port = Number(parsed.port);
+    } catch {
+      // Non-absolute URL — fall back to the raw string as the host label.
+    }
+
+    const detail = causeDetail(err);
+    const data: NetworkErrorData = { operation: context.operation, url, host, cause: code };
+    if (port !== undefined) data.port = port;
+    if (detail) data.detail = detail;
+    if (context.resource) data.resource = context.resource;
+    if (context.setting) data.setting = context.setting;
+
+    // `detail` is appended only when the code has no mapping of its own —
+    // otherwise the explanation already says it better. Without this, wrapping
+    // an unmapped code would *lose* information relative to the raw error.
+    const explained = explain(code, host, port);
+    const isMapped = !explained.startsWith("the request to");
+    const because = isMapped || !detail ? explained : `${explained} (${detail})`;
+
+    const fix = context.setting
+      ? ` Check \`${context.setting}\`${context.resource ? ` on resource '${context.resource}'` : ""}.`
+      : "";
+
+    const message =
+      `${context.operation} failed: cannot reach ${url} — ${code}: ${because}.${fix}`;
+
+    // The wrapped error stays reachable as `cause`: the code mapping is a
+    // convenience, never a reason to destroy what was actually thrown.
+    throw new InvokeError(ERR_NETWORK_UNREACHABLE, message, data, { cause: err });
+  }
+}

package/src/resource-context.ts

@@ -1,5 +1,7 @@
 import type { CancellationSource, InvokeContext, OpenSpan, OpenSpanOptions } from "./cancellation.js";
 import { ControllerContext } from "./controller-context.js";
+import type { Logger } from "./logger.js";
+import type { LoggingHost } from "./log-sink.js";
 import { ControllerPolicy } from "./controller-policy.js";
 import { EvaluationContext } from "./evaluation-context.js";
 import { ModuleContext } from "./module-context.js";
@@ -131,6 +133,28 @@ export interface ResourceContext extends ControllerContext {
    *  manifests. Use this when you need the full kind surface area visible from
    *  the module. */
   loadManifests(url: string): Promise<ResourceManifest[]>;
+  /**
+   * The structured logger for this resource — `kernel/specs/logging.md` §13.2.
+   *
+   * Ambient rather than a resource (D3), because it must work before any
+   * resource initializes. Records are automatically stamped with this
+   * resource's identity, its module, its import-alias scope, and the active
+   * dispatch span's trace and span ids — a controller never passes those.
+   *
+   * A controller emits diagnostics **only** through this. Writing to
+   * stdout/stderr for diagnostic purposes is forbidden; writing to stdout as
+   * *data* (as the `Console` module does) is a separate, legitimate concern and
+   * is unaffected.
+   */
+  readonly log: Logger;
+  /**
+   * Sink attach/detach and drop accounting — the surface a `Telo.Sink`
+   * controller needs and nothing else. §10.2 keeps the sink set open to the
+   * ecosystem, so a third-party sink module reaches the pipeline through this
+   * rather than through a kernel-internal import. Ordinary controllers use
+   * {@link log}.
+   */
+  readonly logging: LoggingHost;
   readonly moduleContext: ModuleContext;
   readonly env: Record<string, string | undefined>;
   readonly stdin: NodeJS.ReadableStream;

package/src/resource-instance.ts

@@ -11,8 +11,26 @@ export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Part
     init?(ctx?: ResourceContext): Promise<void>;
     teardown?(): void | Promise<void>;
     snapshot?(): Record<string, any> | Promise<Record<string, any>>;
+    /**
+     * Teardown ordering hint. Instances tear down in ascending priority — a
+     * higher number means *later*. Default `0`; within one priority the base
+     * order (reverse init) is preserved.
+     *
+     * This exists because the base order is reverse *insertion* order, which the
+     * multi-pass init retry can perturb, so a resource that must reliably outlive
+     * the rest at shutdown cannot express that through the dependency graph. Log
+     * sinks set {@link TEARDOWN_LAST} so they flush after every resource that
+     * might log while shutting down — a generic mechanism, not a logging-specific
+     * carve-out in the teardown path.
+     */
+    teardownPriority?: number;
   };
 
+/** Teardown-last priority (see {@link ResourceInstance.teardownPriority}). Log
+ *  sinks use it so anything logging during its own teardown still reaches a live
+ *  destination. */
+export const TEARDOWN_LAST = 1000;
+
 /** The kind+name an instance was resolved from. */
 export interface RefIdentity {
   kind: string;