@telorun/sdk 0.49.0 → 0.54.0

package/src/log-sink.ts

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

package/src/logger.ts

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

package/src/resolve-ref-instance.ts

@@ -0,0 +1,81 @@
+import type { ModuleContext } from "./module-context.js";
+import type { KindRef } from "./ref.js";
+import { RuntimeError } from "./types.js";
+
+/** The slice of `ResourceContext` needed to resolve a reference. */
+export interface RefResolveContext {
+  readonly moduleContext: ModuleContext;
+}
+
+/**
+ * Resolve a `!ref` config field to a live instance of `T`. Controllers reach
+ * this as `ctx.resolveRef(value, guard, describe, expects)`; the standalone form
+ * is for callers holding only a `{ moduleContext }` slice rather than a full
+ * `ResourceContext`.
+ *
+ * Phase 5 injection normally replaces the slot with the live `ResourceInstance`
+ * before `init()` — local and cross-module refs alike, since injection resolves
+ * an aliased ref through the import's export table (and defers, rather than
+ * leaving a raw ref, when the import hasn't published its exports yet). So the
+ * common path here is the guard short-circuit.
+ *
+ * A raw {@link KindRef} still reaches a controller where injection does not
+ * reach the slot: a kind whose definition yields no field map, or a ref the
+ * controller obtained itself via `ctx.ensureKindRef`. Both are gaps worth
+ * closing in the kernel — until they are, both shapes must be accepted here, and
+ * an aliased ref routes through the import's exported scope because a bare local
+ * lookup would miss it.
+ *
+ * `guard` decides what counts as the right kind of instance — a duck-type check
+ * on the methods the caller will actually invoke, so a mis-wired ref fails with a
+ * clear message here rather than as `undefined is not a function` later.
+ * `describe` labels the owning resource and slot; `expects` names the contract
+ * the slot wants — the slot's own `x-telo-ref` string (`std/cache#Store`) — so
+ * the message says what was missing, not just that something was.
+ *
+ * @example
+ * const store = resolveRefInstance(
+ *   this.resource.store, this.ctx, isKvStore,
+ *   () => `Idempotency.Once "${name}": 'store'`, "std/kv-store#Store",
+ * );
+ */
+export function resolveRefInstance<T>(
+  value: unknown,
+  ctx: RefResolveContext,
+  guard: (candidate: unknown) => candidate is T,
+  describe: () => string,
+  expects?: string,
+): T {
+  // Phase-5-injected: already the instance.
+  if (guard(value)) return value;
+
+  const target = expects ? `resource satisfying \`${expects}\`` : "resource";
+  if (value === undefined || value === null) {
+    throw new RuntimeError("ERR_REF_REQUIRED", `${describe()} is required — reference a ${target}.`);
+  }
+
+  const ref = value as Partial<KindRef<T>>;
+  if (typeof ref.name !== "string") {
+    throw new RuntimeError(
+      "ERR_REF_UNRESOLVED",
+      `${describe()} must be a \`!ref\` to a ${target}.`,
+    );
+  }
+
+  // `Self` names the declaring library's own scope, so it resolves locally —
+  // it is an alias that crosses no import boundary.
+  const instance =
+    ref.alias && ref.alias !== "Self"
+      ? ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name)
+      : ctx.moduleContext.getInstance(ref.name);
+
+  if (!guard(instance)) {
+    const label = ref.alias ? `${ref.alias}.${ref.name}` : ref.name;
+    throw new RuntimeError(
+      "ERR_REF_UNRESOLVED",
+      `${describe()} reference '${label}' did not resolve to a ${target}` +
+        `${instance === undefined ? " (nothing is registered under that name)" : ""}.`,
+    );
+  }
+  return instance;
+}

package/src/resource-context.ts

@@ -1,8 +1,11 @@
 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";
+import type { KindRef } from "./ref.js";
 import { ResourceInstance } from "./resource-instance.js";
 import { ResourceManifest } from "./resource-manifest.js";
 import { RuntimeResource } from "./runtime-resource.js";
@@ -84,7 +87,35 @@ export interface ResourceContext extends ControllerContext {
   spawnChildContext(): EvaluationContext;
   transientChild(context: Record<string, any>): EvaluationContext;
   withManifests<T>(manifests: any[], fn: () => T): T;
+  /**
+   * Normalize a nested slot value to a {@link KindRef}. The value is an inline
+   * definition (`{ kind, …config }`), an already-normalized `{ kind, name }`
+   * ref, or a `!ref` sentinel. An inline definition is *registered* into this
+   * module's scope first — minting `resourceName` (or a generated one) as its
+   * name — so the returned ref always points at a resource the kernel knows.
+   *
+   * The inverse of {@link resolveRef}: this goes slot value → ref, that goes
+   * ref → live instance. Controllers that dispatch through
+   * `invokeResolved(kind, name, …)` want the ref, so the invocation keeps its
+   * identity for tracing and error wrapping.
+   */
+  ensureKindRef(value: any, resourceName?: string): KindRef;
+  /** @deprecated Renamed to {@link ensureKindRef} — it produces a reference
+   *  (registering an inline definition on the way), it does not resolve one. */
   resolveChildren(resource: any, resourceName?: string): { kind: string; name: string };
+  /**
+   * Resolve a `!ref` config field to a live instance of `T`. See
+   * {@link resolveRefInstance} — this is the same resolution, reached through
+   * the context a controller already holds. `expects` names the contract the
+   * slot wants — its `x-telo-ref` string (`std/cache#Store`) — so a mis-wire
+   * says what was missing.
+   */
+  resolveRef<T>(
+    value: unknown,
+    guard: (candidate: unknown) => candidate is T,
+    describe: () => string,
+    expects?: string,
+  ): T;
   validateSchema(value: any, schema: any): void;
   createSchemaValidator(schema: any): DataValidator;
   registerSchema(name: string, schema: object): void;
@@ -131,6 +162,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;