@telorun/sdk 0.48.0 → 0.50.0

package/dist/network-fetch.d.ts

@@ -0,0 +1,71 @@
+/** 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 declare 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;
+}
+/**
+ * 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 declare function networkCauseCode(err: unknown): string | 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 declare function fetchOrThrow(input: string | URL, init: RequestInit | undefined, context: {
+    operation: string;
+    resource?: string;
+    setting?: string;
+}): Promise<Response>;
+//# sourceMappingURL=network-fetch.d.ts.map

package/dist/network-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-fetch.d.ts","sourceRoot":"","sources":["../src/network-fetch.ts"],"names":[],"mappings":"AAGA;;yBAEyB;AACzB,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AAEjE;;;;;;;mEAOmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd;;iDAE6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;gEAC4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;6DAGyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiDD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,GAAG,GAAG,EACnB,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAClE,OAAO,CAAC,QAAQ,CAAC,CA4CnB"}

package/dist/network-fetch.js

@@ -0,0 +1,140 @@
+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";
+/** 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, host, port) {
+    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) {
+    let current = err;
+    let detail;
+    for (let depth = 0; current && depth < 5; depth++) {
+        const message = current.message;
+        if (typeof message === "string" && message && message !== "fetch failed")
+            detail = message;
+        current = current.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) {
+    let current = err;
+    for (let depth = 0; current && depth < 5; depth++) {
+        const code = current.code;
+        if (typeof code === "string")
+            return code;
+        current = current.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, init, context) {
+    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;
+        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 = { 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/dist/resource-context.d.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";
@@ -119,6 +121,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/dist/resource-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-context.d.ts","sourceRoot":"","sources":["../src/resource-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource-context.d.ts","sourceRoot":"","sources":["../src/resource-context.ts"],"names":[],"mappings":"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"}

package/dist/resource-instance.d.ts

@@ -6,7 +6,24 @@ 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 declare const TEARDOWN_LAST = 1000;
 /** The kind+name an instance was resolved from. */
 export interface RefIdentity {
     kind: string;

package/dist/resource-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG;IAC3B,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;CACjE,CAAC;AAEJ,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,MAAuC,CAAC;AAE1E;sFACsF;AACtF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CASnF;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAExE"}
+{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG;IAC3B,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAChE;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEJ;;mBAEmB;AACnB,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,MAAuC,CAAC;AAE1E;sFACsF;AACtF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CASnF;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAExE"}

package/dist/resource-instance.js

@@ -1,3 +1,7 @@
+/** 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;
 /**
  * Non-enumerable identity tag the kernel stamps on a live instance when it
  * injects a resolved `!ref` into a slot. A consumer that holds only the bare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sdk",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "Telo SDK - Public API for Telo module authors.",
   "keywords": [
     "telo",

package/src/index.ts

@@ -17,6 +17,11 @@ export * from "./resource-context.js";
 export * from "./resource-instance.js";
 export * from "./resource-manifest.js";
 export * from "./invoke-error.js";
+export * from "./log-record.js";
+export * from "./log-sink.js";
+export * from "./log-severity.js";
+export * from "./logger.js";
+export * from "./network-fetch.js";
 export * from "./runtime-error.js";
 export * from "./runtime-event.js";
 export * from "./runtime-resource.js";

package/src/invoke-error.ts

@@ -11,7 +11,7 @@ export class InvokeError extends Error {
   readonly code: string;
   readonly data?: unknown;
 
-  constructor(code: string, message: string, data?: unknown) {
+  constructor(code: string, message: string, data?: unknown, options?: { cause?: unknown }) {
     super(message);
     this.name = "InvokeError";
     this.code = code;
@@ -27,6 +27,19 @@ export class InvokeError extends Error {
       writable: false,
       configurable: false,
     });
+    // Preserve the error being wrapped. Defined rather than assigned so it is
+    // non-enumerable — matching how the Error constructor's own `cause` option
+    // behaves, and keeping it out of JSON serialisation / CEL property access
+    // for the same reason as the marker above. (`ErrorOptions` is not in this
+    // package's TS lib, hence the local option type.)
+    if (options && "cause" in options) {
+      Object.defineProperty(this, "cause", {
+        value: options.cause,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+      });
+    }
   }
 }
 

package/src/log-record.ts

@@ -0,0 +1,113 @@
+import type { SeverityNumber } from "./log-severity.js";
+
+/**
+ * The Telo log record model — `kernel/specs/logging.md` §4. Maps 1:1 onto an
+ * OpenTelemetry `LogRecord`; encodings (§11) determine spelling and MUST NOT add
+ * or remove semantics.
+ *
+ * The one deliberate deviation from OTel is {@link LogRecord.message}: OTel's
+ * `Body` is an `AnyValue` and may be structured, while Telo requires a string and
+ * routes structured data to `attributes`. That keeps the console encoding total —
+ * every record has a renderable headline — and matches slog, pino, and zap.
+ */
+
+/** The attribute value type (§6.1). `null` is a valid value and is preserved. */
+export type AnyValue =
+  | string
+  | boolean
+  | number
+  | bigint
+  | Uint8Array
+  | null
+  | AnyValue[]
+  | { [key: string]: AnyValue };
+
+export type LogAttributes = Record<string, AnyValue>;
+
+/** Structured error (§4.2). The `cause` chain is bounded per §6.3. */
+export interface ErrorValue {
+  /** Error class or code, e.g. `ERR_INVOKE_CANCELLED`. */
+  type: string;
+  message: string;
+  /** Multi-line, unmodified. */
+  stack?: string;
+  cause?: ErrorValue;
+}
+
+/** The emitting Telo resource (§7.3). `id` is the full hierarchical id, which is
+ *  what distinguishes two instances of the same templated kind. */
+export interface ResourceRef {
+  kind: string;
+  name: string;
+  id?: string;
+}
+
+export interface LogRecord {
+  /** Nanoseconds since the Unix epoch, by the origin clock. */
+  timestamp: bigint;
+  /** When the runtime observed the event, when that differs from `timestamp`
+   *  (a bridged third-party logger, §13.3). */
+  observedTimestamp?: bigint;
+  severityNumber: SeverityNumber;
+  /** Canonical short name, or the original source spelling when bridging. */
+  severityText: string;
+  /** May be empty; never absent. */
+  message: string;
+  attributes?: LogAttributes;
+  /** 32 lowercase hex chars. */
+  traceId?: string;
+  /** 16 lowercase hex chars. Never present without `traceId`. */
+  spanId?: string;
+  /** Bit 0 = sampled, bit 1 reserved (§7.5), bits 2–7 zero. */
+  traceFlags?: number;
+  resource?: ResourceRef;
+  /** Module name of the emitter. Not unique — see `scope`. */
+  module?: string;
+  /** Dotted import-alias path identifying which *instance* emitted the record
+   *  (`Api.Domain.Db`). Absent for the root Application's own resources. */
+  scope?: string;
+  /** Identifies a class of event; max 256 chars. */
+  eventName?: string;
+  error?: ErrorValue;
+  /** Non-zero when §6.3 limits truncated attributes. */
+  droppedAttributesCount?: number;
+}
+
+// Written as `BigInt(...)` rather than as `1_000_000n` literals: this module is
+// consumed from source by the browser-targeted editor, whose tsconfig targets
+// below ES2020 and cannot parse the literal syntax.
+const NANOS_PER_MS = BigInt(1_000_000);
+const NANOS_PER_SECOND = BigInt(1_000_000_000);
+
+/**
+ * Node has no true nanosecond wall clock: `Date` is millisecond-resolution and
+ * `hrtime.bigint()` is monotonic rather than epoch-anchored. The best available
+ * is the performance origin plus the monotonic offset, which yields microsecond
+ * resolution zero-padded to nine digits. Format-conformant with §11.1; the extra
+ * three digits are always zero.
+ *
+ * The origin is captured once as a bigint so the addition never routes a
+ * 16-significant-digit value through a float64 and loses the low microseconds.
+ */
+const ORIGIN_NANOS = BigInt(Math.round(performance.timeOrigin * 1e6));
+
+export function nowUnixNano(): bigint {
+  return ORIGIN_NANOS + BigInt(Math.round(performance.now() * 1e6));
+}
+
+/** Epoch nanoseconds for a millisecond-resolution instant — used when bridging a
+ *  third-party record that carries a `Date` or epoch-millis timestamp. */
+export function unixNanoFromMillis(epochMillis: number): bigint {
+  return BigInt(Math.round(epochMillis)) * NANOS_PER_MS;
+}
+
+/**
+ * RFC 3339, UTC, nanosecond precision, `Z` suffix — the `time` key of the `json`
+ * encoding (§11.1).
+ */
+export function formatUnixNano(timestamp: bigint): string {
+  const seconds = timestamp / NANOS_PER_SECOND;
+  const nanos = timestamp - seconds * NANOS_PER_SECOND;
+  const isoSeconds = new Date(Number(seconds) * 1000).toISOString().slice(0, 19);
+  return `${isoSeconds}.${nanos.toString().padStart(9, "0")}Z`;
+}

package/src/log-severity.ts

@@ -0,0 +1,128 @@
+/**
+ * The OpenTelemetry `SeverityNumber` scale (1–24, stable), which Telo adopts
+ * verbatim — see `kernel/specs/logging.md` §5.
+ *
+ * Higher is more severe. All comparison, filtering, and threshold logic uses the
+ * number; severity *text* is presentation only and MUST NOT be compared. The
+ * full 24-value range stays valid on the wire so records bridged from a
+ * third-party logger survive a round-trip with their original spelling intact.
+ */
+
+/** An OTel SeverityNumber. `0` (UNSPECIFIED) is never emitted by a Telo runtime. */
+export type SeverityNumber = number;
+
+/** The six levels Telo names. Each is the floor of its four-value OTel range. */
+export const SEVERITY = {
+  trace: 1,
+  debug: 5,
+  info: 9,
+  warn: 13,
+  error: 17,
+  fatal: 21,
+} as const;
+
+export type LevelName = keyof typeof SEVERITY;
+
+export const LEVEL_NAMES: readonly LevelName[] = ["trace", "debug", "info", "warn", "error", "fatal"];
+
+/** The severity at or above which a record describes an error (§5.1). This is
+ *  the portable error predicate; runtimes expose it rather than re-deriving it. */
+export const ERROR_SEVERITY_FLOOR = 17;
+
+const FLOORS: readonly number[] = [1, 5, 9, 13, 17, 21];
+
+const TEXT_BY_FLOOR: Readonly<Record<number, string>> = {
+  1: "TRACE",
+  5: "DEBUG",
+  9: "INFO",
+  13: "WARN",
+  17: "ERROR",
+  21: "FATAL",
+};
+
+/**
+ * The range floor for a severity number — the canonical level a value maps onto.
+ * Out-of-range values clamp into 1–24 rather than producing `0`, which §5.1
+ * forbids emitting.
+ */
+export function severityFloor(severity: SeverityNumber): number {
+  const clamped = severity < 1 ? 1 : severity > 24 ? 24 : Math.trunc(severity);
+  let floor = FLOORS[0]!;
+  for (const candidate of FLOORS) {
+    if (candidate <= clamped) floor = candidate;
+    else break;
+  }
+  return floor;
+}
+
+/** Canonical short name (`TRACE`…`FATAL`) for a severity number. */
+export function severityText(severity: SeverityNumber): string {
+  return TEXT_BY_FLOOR[severityFloor(severity)]!;
+}
+
+/** `true` when the record describes an error (§5.1). */
+export function isErrorSeverity(severity: SeverityNumber): boolean {
+  return severity >= ERROR_SEVERITY_FLOOR;
+}
+
+/** Resolve a manifest `level:` name to its severity number. */
+export function severityForLevel(level: LevelName): number {
+  return SEVERITY[level];
+}
+
+/**
+ * Map a level name of unknown provenance onto the scale. A name Telo does not
+ * recognize yields `undefined` so the caller can preserve the original spelling
+ * in `severity_text` while landing the number on a range floor (§5.1).
+ */
+export function parseLevelName(name: string): number | undefined {
+  const key = name.trim().toLowerCase();
+  // Own-property check, not `in`: `in` also matches inherited members, so
+  // `parseLevelName("toString")` would otherwise return a Function and defeat
+  // the `?? fallback` at every call site. Written as `hasOwnProperty.call`
+  // rather than `Object.hasOwn` because this module is consumed from source by
+  // the browser-targeted editor, whose tsconfig targets below ES2022.
+  return Object.prototype.hasOwnProperty.call(SEVERITY, key)
+    ? SEVERITY[key as LevelName]
+    : undefined;
+}
+
+/**
+ * Go's `log/slog` documents that subtracting 9 from an OTel severity converts it
+ * to the slog range — an exact, officially sanctioned relation, so a Go runtime
+ * uses arithmetic rather than a table (§5.2). Exposed here so the conformance
+ * vectors can assert the relation from the Node side too.
+ */
+export const SLOG_OFFSET = 9;
+
+/**
+ * pino's scale is 10× and offset, with no arithmetic relation to OTel, so §5.2
+ * requires a table. Used by the Fastify logger replacement (§13.3).
+ */
+const PINO_BY_SEVERITY: Readonly<Record<number, number>> = {
+  1: 10,
+  5: 20,
+  9: 30,
+  13: 40,
+  17: 50,
+  21: 60,
+};
+
+const SEVERITY_BY_PINO: Readonly<Record<number, number>> = {
+  10: 1,
+  20: 5,
+  30: 9,
+  40: 13,
+  50: 17,
+  60: 21,
+};
+
+export function pinoLevelForSeverity(severity: SeverityNumber): number {
+  return PINO_BY_SEVERITY[severityFloor(severity)]!;
+}
+
+/** `undefined` for a pino level Telo does not name, so the caller preserves the
+ *  source spelling and falls back to the nearest floor. */
+export function severityForPinoLevel(level: number): number | undefined {
+  return SEVERITY_BY_PINO[level];
+}