@telorun/sdk 0.49.0 → 0.50.0

package/dist/index.d.ts

@@ -17,6 +17,10 @@ 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";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -17,6 +17,10 @@ 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";

package/dist/log-record.d.ts

@@ -0,0 +1,72 @@
+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;
+}
+export declare function nowUnixNano(): bigint;
+/** Epoch nanoseconds for a millisecond-resolution instant — used when bridging a
+ *  third-party record that carries a `Date` or epoch-millis timestamp. */
+export declare function unixNanoFromMillis(epochMillis: number): bigint;
+/**
+ * RFC 3339, UTC, nanosecond precision, `Z` suffix — the `time` key of the `json`
+ * encoding (§11.1).
+ */
+export declare function formatUnixNano(timestamp: bigint): string;
+//# sourceMappingURL=log-record.d.ts.map

package/dist/log-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-record.d.ts","sourceRoot":"","sources":["../src/log-record.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;;;;;GASG;AAEH,iFAAiF;AACjF,MAAM,MAAM,QAAQ,GAChB,MAAM,GACN,OAAO,GACP,MAAM,GACN,MAAM,GACN,UAAU,GACV,IAAI,GACJ,QAAQ,EAAE,GACV;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAA;CAAE,CAAC;AAEhC,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAErD,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED;mEACmE;AACnE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB;iDAC6C;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;8EAC0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,sDAAsD;IACtD,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAoBD,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;0EAC0E;AAC1E,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxD"}

package/dist/log-record.js

@@ -0,0 +1,34 @@
+// 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() {
+    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) {
+    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) {
+    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/dist/log-severity.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 declare const SEVERITY: {
+    readonly trace: 1;
+    readonly debug: 5;
+    readonly info: 9;
+    readonly warn: 13;
+    readonly error: 17;
+    readonly fatal: 21;
+};
+export type LevelName = keyof typeof SEVERITY;
+export declare const LEVEL_NAMES: readonly LevelName[];
+/** 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 declare const ERROR_SEVERITY_FLOOR = 17;
+/**
+ * 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 declare function severityFloor(severity: SeverityNumber): number;
+/** Canonical short name (`TRACE`…`FATAL`) for a severity number. */
+export declare function severityText(severity: SeverityNumber): string;
+/** `true` when the record describes an error (§5.1). */
+export declare function isErrorSeverity(severity: SeverityNumber): boolean;
+/** Resolve a manifest `level:` name to its severity number. */
+export declare function severityForLevel(level: LevelName): number;
+/**
+ * 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 declare function parseLevelName(name: string): number | 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 declare const SLOG_OFFSET = 9;
+export declare function pinoLevelForSeverity(severity: SeverityNumber): number;
+/** `undefined` for a pino level Telo does not name, so the caller preserves the
+ *  source spelling and falls back to the nearest floor. */
+export declare function severityForPinoLevel(level: number): number | undefined;
+//# sourceMappingURL=log-severity.d.ts.map

package/dist/log-severity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-severity.d.ts","sourceRoot":"","sources":["../src/log-severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC,iFAAiF;AACjF,eAAO,MAAM,QAAQ;;;;;;;CAOX,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,QAAQ,CAAC;AAE9C,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAAyD,CAAC;AAEtG;mFACmF;AACnF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAavC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAQ9D;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAE7D;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAEjE;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU/D;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,IAAI,CAAC;AAwB7B,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAErE;AAED;2DAC2D;AAC3D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEtE"}

package/dist/log-severity.js

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ */
+/** 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,
+};
+export const LEVEL_NAMES = ["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 = [1, 5, 9, 13, 17, 21];
+const TEXT_BY_FLOOR = {
+    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) {
+    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) {
+    return TEXT_BY_FLOOR[severityFloor(severity)];
+}
+/** `true` when the record describes an error (§5.1). */
+export function isErrorSeverity(severity) {
+    return severity >= ERROR_SEVERITY_FLOOR;
+}
+/** Resolve a manifest `level:` name to its severity number. */
+export function severityForLevel(level) {
+    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) {
+    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]
+        : 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 = {
+    1: 10,
+    5: 20,
+    9: 30,
+    13: 40,
+    17: 50,
+    21: 60,
+};
+const SEVERITY_BY_PINO = {
+    10: 1,
+    20: 5,
+    30: 9,
+    40: 13,
+    50: 17,
+    60: 21,
+};
+export function pinoLevelForSeverity(severity) {
+    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) {
+    return SEVERITY_BY_PINO[level];
+}

package/dist/log-sink.d.ts

@@ -0,0 +1,91 @@
+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 declare const DEFAULT_BUFFER_POLICY: SinkBufferPolicy;
+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 declare function blockUnsupportedMessage(sinkId: string): string;
+export declare const BLOCK_UNSUPPORTED = "ERR_LOG_SINK_ON_FULL_UNSUPPORTED";
+//# sourceMappingURL=log-sink.d.ts.map

package/dist/log-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-sink.d.ts","sourceRoot":"","sources":["../src/log-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,gBAAgB,GAAG,YAAY,CAAC;AAEpF;;cAEc;AACd,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,qBAAqB,EAAE,gBAInC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B;uDACmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;8BAE0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC;8DAC0D;IAC1D,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAE/B,4BAA4B;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;qDAGiD;IACjD,SAAS,IAAI,IAAI,CAAC;IAElB,8EAA8E;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IACpC,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IACpC;6EACyE;IACzE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IAC5C;;;2CAGuC;IACvC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpE;AAED;;;;aAIa;AACb,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,eAAO,MAAM,iBAAiB,qCAAqC,CAAC"}

package/dist/log-sink.js

@@ -0,0 +1,16 @@
+export const DEFAULT_BUFFER_POLICY = {
+    buffer: 8192,
+    onFull: "drop_new",
+    flushIntervalMs: 1000,
+};
+/** 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) {
+    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/dist/logger.d.ts

@@ -0,0 +1,85 @@
+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 declare function isLogValuer(value: unknown): value is LogValuer;
+/** A logger that discards everything. Used where a logger is structurally
+ *  required before one is available, and by tests that assert silence. */
+export declare const NOOP_LOGGER: Logger;
+/** 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 declare function mergeBoundAttributes(bound: LogAttributes | undefined, record: LogAttributes | undefined): LogAttributes | undefined;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,UAAU,IAAI,QAAQ,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,SAAS,CAAC;AACrD,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAEnE;gFACgF;AAChF,MAAM,WAAW,UAAU;IACzB;0CACsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;0EACsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;2EACuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,MAAM;IACrB;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC;IAE3C;;;;OAIG;IACH,GAAG,CACD,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,kBAAkB,EAC/B,OAAO,CAAC,EAAE,UAAU,GACnB,IAAI,CAAC;IAER;;;;OAIG;IACH,IAAI,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAAC;IAE7C,mEAAmE;IACnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACpF,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACpF,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACnF,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACnF,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACpF;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;CACrF;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAM9D;AAED;0EAC0E;AAC1E,eAAO,MAAM,WAAW,EAAE,MAWzB,CAAC;AAEF;;kCAEkC;AAClC,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,aAAa,GAAG,SAAS,CAI3B"}

package/dist/logger.js

@@ -0,0 +1,30 @@
+/** Resolve a {@link LogValuer} if the value is one, else pass it through. */
+export function isLogValuer(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.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 = {
+    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, record) {
+    if (!bound)
+        return record;
+    if (!record)
+        return bound;
+    return { ...bound, ...record };
+}

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":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACtG,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,WAAW,WAAW;IAC1B;gFAC4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;4EAGwE;IACxE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,aAAc,YAAW,aAAa;IACjD,OAAO;IAIP,QAAQ;CAGT;AAED,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAC,GAAG;IAAE,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEhG,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;;;4EAKwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IACzC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD;;iCAE6B;IAC7B,wBAAwB,IAAI,kBAAkB,CAAC;IAC/C;;;;;2EAKuE;IACvE,WAAW,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9C;;;;;kBAKc;IACd,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpF,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1F,cAAc,CAAC,OAAO,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,OAAO,EACf,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAAC,GAAG,CAAC,CAAC;IAChB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;IACvE,gBAAgB,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAC;IACtC,iBAAiB,IAAI,iBAAiB,CAAC;IACvC,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAAC;IAChE,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACnD,eAAe,CAAC,QAAQ,EAAE,GAAG,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtF,cAAc,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC;IAC9C,qBAAqB,CAAC,MAAM,EAAE,GAAG,GAAG,aAAa,CAAC;IAClD,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC/C,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACzD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,GAAG,SAAS,CAAC;IACtD,kFAAkF;IAClF,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,aAAa,CAAC;IACtF,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjG,kBAAkB,CAAC,UAAU,EAAE,GAAG,GAAG,IAAI,CAAC;IAC1C;yDACqD;IACrD,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3F;;;;OAIG;IACH,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAAC;IACpD;;;;;;;;;;;OAWG;IACH,WAAW,IAAI,MAAM,GAAG,SAAS,CAAC;IAClC;;;;iEAI6D;IAC7D,cAAc,IAAI,MAAM,GAAG,SAAS,CAAC;IACrC;wDACoD;IACpD,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC5E;;;sBAGkB;IAClB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACxD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;CACxC"}
+{"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.49.0",
+  "version": "0.50.0",
   "description": "Telo SDK - Public API for Telo module authors.",
   "keywords": [
     "telo",

package/src/index.ts

@@ -17,6 +17,10 @@ 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";

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];
+}

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/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;