@telorun/kernel 0.49.0 → 0.50.0

package/src/logging/record-buffer.ts

@@ -0,0 +1,72 @@
+import type { LogRecord } from "@telorun/sdk";
+import type { SinkBufferPolicy } from "./log-sink.js";
+
+/**
+ * The bounded buffer every asynchronous sink composes — `kernel/specs/logging.md`
+ * §10.3.
+ *
+ * The ecosystems disagree by default: Rust's `tracing-appender` drops, zap
+ * buffers 256 kB / 30 s, and pino has no bound at all. Telo therefore makes the
+ * policy explicit and required, and the buffer is never unbounded.
+ *
+ * `drop_old` has no precedent among the surveyed libraries, so it is implemented
+ * as specified — true ring-buffer semantics, evicting the oldest record — rather
+ * than by analogy to something else.
+ */
+export class RecordBuffer {
+  readonly #capacity: number;
+  readonly #policy: SinkBufferPolicy;
+  readonly #onDrop: () => void;
+  #items: LogRecord[] = [];
+  /** Index of the oldest record, so `drop_old` evicts in O(1) instead of
+   *  shifting the whole array on every overflow. */
+  #head = 0;
+
+  constructor(policy: SinkBufferPolicy, onDrop: () => void) {
+    this.#capacity = Math.max(1, policy.buffer);
+    this.#policy = policy;
+    this.#onDrop = onDrop;
+  }
+
+  get size(): number {
+    return this.#items.length - this.#head;
+  }
+
+  get isFull(): boolean {
+    return this.size >= this.#capacity;
+  }
+
+  push(record: LogRecord): void {
+    if (this.isFull) {
+      if (this.#policy.onFull === "drop_old") {
+        this.#head += 1;
+        this.#compact();
+      } else {
+        // `drop_new` — and `block`, which never reaches here because a runtime
+        // that cannot honour it rejects the manifest at load rather than
+        // silently degrading to a dropping policy.
+        this.#onDrop();
+        return;
+      }
+      this.#onDrop();
+    }
+    this.#items.push(record);
+  }
+
+  /** Take everything buffered, leaving the buffer empty. */
+  drain(): LogRecord[] {
+    const drained = this.#head === 0 ? this.#items : this.#items.slice(this.#head);
+    this.#items = [];
+    this.#head = 0;
+    return drained;
+  }
+
+  #compact(): void {
+    // Reclaim the consumed prefix once it dominates the array, so a long-lived
+    // ring does not grow its backing store without bound.
+    if (this.#head > 32 && this.#head * 2 >= this.#items.length) {
+      this.#items = this.#items.slice(this.#head);
+      this.#head = 0;
+    }
+  }
+}

package/src/logging/redact-attributes.ts

@@ -0,0 +1,168 @@
+import { parseRedactionPath, type RedactionSegment } from "@telorun/analyzer";
+import type { AnyValue, ErrorValue, LogAttributes } from "@telorun/sdk";
+
+/**
+ * Path-based redaction — `kernel/specs/logging.md` §14.
+ *
+ * Only path-based redaction is portable across Node, Rust, and Go, so it is the
+ * only form specified normatively. Paths are compiled once at configuration
+ * time by the analyzer's hand-written parser (never by compiling source in the
+ * host language, §14.1) and applied here by *navigating* to each path rather
+ * than walking the whole value tree — which is what keeps an explicit path at
+ * §14.2's 1–2% cost instead of the 25–55% an intermediate wildcard pays.
+ *
+ * The key is always preserved and only the value replaced. Deletion destroys
+ * schema stability and hides that a field was present at all, so `remove` is
+ * offered for the cases that genuinely need it but is never the default.
+ */
+
+export const DEFAULT_CENSOR = "[redacted]";
+
+export interface RedactionPolicy {
+  paths: readonly CompiledRedactionPath[];
+  censor: string;
+  remove: boolean;
+}
+
+export interface CompiledRedactionPath {
+  /** The path as written, kept for diagnostics. */
+  source: string;
+  segments: readonly RedactionSegment[];
+}
+
+/** Compile a policy's paths once, at configuration time. Throws
+ *  `RedactionPathError` with the offending offset, so a bad path fails the
+ *  manifest rather than silently failing to redact at runtime. */
+export function compileRedactionPolicy(config: {
+  paths?: readonly string[];
+  censor?: string;
+  remove?: boolean;
+}): RedactionPolicy {
+  return {
+    paths: (config.paths ?? []).map((source) => ({
+      source,
+      segments: parseRedactionPath(source),
+    })),
+    censor: config.censor ?? DEFAULT_CENSOR,
+    remove: config.remove ?? false,
+  };
+}
+
+export const EMPTY_REDACTION_POLICY: RedactionPolicy = {
+  paths: [],
+  censor: DEFAULT_CENSOR,
+  remove: false,
+};
+
+/** Apply the policy to a record's attributes in place. The attributes have
+ *  already been normalized (§6.3), so collections are bounded and no cycle can
+ *  make the navigation diverge. */
+export function redactAttributes(
+  attributes: LogAttributes | undefined,
+  policy: RedactionPolicy,
+): void {
+  if (!attributes || policy.paths.length === 0) return;
+  for (const path of policy.paths) applyPath(attributes, path.segments, policy);
+}
+
+/** Redaction applies to the error as well as the attributes (§14). The error's
+ *  own fields are structural rather than user data, so a path addresses them by
+ *  their record spelling — `error.message`, `error.cause.message`. */
+export function redactError(error: ErrorValue | undefined, policy: RedactionPolicy): void {
+  if (!error || policy.paths.length === 0) return;
+  const wrapper: LogAttributes = { error: error as unknown as AnyValue };
+  for (const path of policy.paths) applyPath(wrapper, path.segments, policy);
+}
+
+function applyPath(
+  root: LogAttributes,
+  segments: readonly RedactionSegment[],
+  policy: RedactionPolicy,
+): void {
+  if (segments.length === 0) return;
+
+  let frontier: unknown[] = [root];
+
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    const segment = segments[i]!;
+    const next: unknown[] = [];
+    for (const container of frontier) {
+      if (segment.kind === "wildcard") {
+        for (const child of childrenOf(container)) next.push(child);
+      } else {
+        const child = readKey(container, segment.name);
+        if (child !== undefined) next.push(child);
+      }
+    }
+    if (next.length === 0) return;
+    frontier = next;
+  }
+
+  const last = segments[segments.length - 1]!;
+  for (const container of frontier) {
+    if (last.kind === "wildcard") {
+      // Descending so that `remove: true` over an array — which splices each
+      // matched index — does not shift the indices still to be visited. Without
+      // this, `items[*]` with remove leaves every other element behind, which
+      // for the §14 security control means a secret is only partially removed.
+      // Order is irrelevant for the censor path.
+      const keys = keysOf(container);
+      for (let i = keys.length - 1; i >= 0; i -= 1) writeKey(container, keys[i]!, policy);
+    } else {
+      if (readKey(container, last.name) === undefined && !hasKey(container, last.name)) continue;
+      writeKey(container, last.name, policy);
+    }
+  }
+}
+
+function childrenOf(container: unknown): unknown[] {
+  if (Array.isArray(container)) return container;
+  if (isPlainContainer(container)) return Object.values(container);
+  return [];
+}
+
+function keysOf(container: unknown): (string | number)[] {
+  if (Array.isArray(container)) return container.map((_item, index) => index);
+  if (isPlainContainer(container)) return Object.keys(container);
+  return [];
+}
+
+function readKey(container: unknown, key: string): unknown {
+  if (Array.isArray(container)) {
+    const index = Number(key);
+    return Number.isInteger(index) ? container[index] : undefined;
+  }
+  if (isPlainContainer(container)) return container[key];
+  return undefined;
+}
+
+function hasKey(container: unknown, key: string): boolean {
+  if (Array.isArray(container)) {
+    const index = Number(key);
+    return Number.isInteger(index) && index >= 0 && index < container.length;
+  }
+  return isPlainContainer(container) && hasOwn(container, key);
+}
+
+function hasOwn(container: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(container, key);
+}
+
+function writeKey(container: unknown, key: string | number, policy: RedactionPolicy): void {
+  if (Array.isArray(container)) {
+    const index = typeof key === "number" ? key : Number(key);
+    if (!Number.isInteger(index)) return;
+    if (policy.remove) container.splice(index, 1);
+    else container[index] = policy.censor;
+    return;
+  }
+  if (!isPlainContainer(container)) return;
+  const name = String(key);
+  if (!hasOwn(container, name)) return;
+  if (policy.remove) delete container[name];
+  else container[name] = policy.censor;
+}
+
+function isPlainContainer(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !(value instanceof Uint8Array);
+}

package/src/logging/sampler.ts

@@ -0,0 +1,76 @@
+import { isErrorSeverity, type LogRecord } from "@telorun/sdk";
+
+/**
+ * Sampling — `kernel/specs/logging.md` §15. Off by default.
+ *
+ * The dedup key is (`severity_number`, `message`) rather than the attributes,
+ * which is what keeps it cheap: a repeated message throttles regardless of the
+ * per-occurrence data hanging off it.
+ *
+ * §15 permits a fixed-size counter table that accepts collisions, trading
+ * precision for speed. This implementation instead keeps an
+ * **insertion-ordered map bounded by an entry cap**, evicting the least recently
+ * created key on overflow. Memory stays bounded either way, but a collision can
+ * only ever *lose* a record that should have been emitted, and no throughput
+ * gain justified that.
+ */
+
+export interface SamplingConfig {
+  /** Records emitted unconditionally at the start of each window. */
+  first: number;
+  /** Thereafter every Nth record is emitted. `0` drops everything after the
+   *  first `first` in the window. */
+  thereafter: number;
+  /** Window length in milliseconds. */
+  tickMs: number;
+  /** Records at ERROR and above are not sampled by default (§15). */
+  sampleErrors?: boolean;
+}
+
+const MAX_TRACKED_KEYS = 4096;
+
+interface Window {
+  start: number;
+  count: number;
+}
+
+export class Sampler {
+  readonly #config: SamplingConfig;
+  readonly #windows = new Map<string, Window>();
+
+  constructor(config: SamplingConfig) {
+    this.#config = config;
+  }
+
+  /** `true` when the record should be emitted, `false` when it is sampled out.
+   *  A `false` result is counted under cause `sampled` by the caller. */
+  shouldEmit(record: LogRecord, now: number): boolean {
+    if (!this.#config.sampleErrors && isErrorSeverity(record.severityNumber)) return true;
+
+    const key = `${record.severityNumber}\x00${record.message}`;
+    let window = this.#windows.get(key);
+
+    if (!window || now - window.start >= this.#config.tickMs) {
+      window = { start: now, count: 0 };
+      this.#windows.delete(key);
+      this.#windows.set(key, window);
+      this.#evictOverflow();
+    }
+
+    window.count += 1;
+
+    if (window.count <= this.#config.first) return true;
+    if (this.#config.thereafter <= 0) return false;
+
+    const sinceFirst = window.count - this.#config.first;
+    return sinceFirst % this.#config.thereafter === 0;
+  }
+
+  #evictOverflow(): void {
+    while (this.#windows.size > MAX_TRACKED_KEYS) {
+      const oldest = this.#windows.keys().next();
+      if (oldest.done) return;
+      this.#windows.delete(oldest.value);
+    }
+  }
+}

package/src/logging/scope-config.ts

@@ -0,0 +1,32 @@
+import type { LogAttributes } from "@telorun/sdk";
+import type { RedactionPolicy } from "./redact-attributes.js";
+import type { SamplingConfig } from "./sampler.js";
+
+/**
+ * Per-module-context logging configuration — `kernel/specs/logging.md` §12.2.
+ *
+ * Resolved once when the import graph is built and held as plain values: there
+ * is no per-record lookup and no walk up the import chain at emit time.
+ *
+ * This is a **leaf type module** on purpose. `ScopeConfig` is stamped onto the
+ * generic `ModuleContext` and read by `internal-context` / `resource-context`,
+ * so having those import it from the 400-line `logging-pipeline` would point
+ * generic core plumbing at a specific subsystem's implementation. Keeping the
+ * type here — depending only on the two policy leaves and the SDK — keeps that
+ * dependency pointing at a type, not at the pipeline.
+ */
+export interface ScopeConfig {
+  /** The resolved level for this module context. Also the default a sink's own
+   *  `level` falls back to (§12.1). */
+  threshold: number;
+  redaction: RedactionPolicy;
+  sampling?: SamplingConfig;
+  /** Values bound to the manifest's `secrets:`, redacted with no configuration
+   *  (§14). Cascades down the import graph exactly as the threshold does. */
+  secretValues?: ReadonlySet<string>;
+  /** Dotted import-alias path of the emitting module context. Absent at root. */
+  scope?: string;
+  module?: string;
+  /** Resource-level attributes merged into every record from this scope. */
+  attributes?: LogAttributes;
+}

package/src/logging/span-id.ts

@@ -0,0 +1,84 @@
+import { randomBytes } from "node:crypto";
+
+/**
+ * Span and trace identifier formatting — `kernel/specs/logging.md` §7.1 (D7).
+ *
+ * The internal representation is unconstrained; only the emitted form is
+ * normative. Telo keeps span ids as a native counter — minting is an increment,
+ * comparison and map-keying stay cheap, nothing allocates — and renders the
+ * 16-character hex form **only at the encoding boundary**, on records actually
+ * being emitted to a sink that needs it. Ids are never formatted eagerly at span
+ * creation.
+ *
+ * Zero-padding is enforced here rather than left to a caller because it is a
+ * live bug class, not a formality: rendering a fixed-width byte array through a
+ * general integer formatter silently produces a short, spec-invalid id whenever
+ * the value has leading zero bytes.
+ */
+
+const SPAN_ID_HEX_LENGTH = 16;
+const TRACE_ID_HEX_LENGTH = 32;
+const U64_MASK = (1n << 64n) - 1n;
+
+/**
+ * An 8-byte per-process salt, minted once at startup. A bare counter starting at
+ * 1 collides across processes participating in one distributed trace — two
+ * services would both mint span id `1`. XORing costs a single operation,
+ * preserves the cheap counter internally, and keeps ids unique within a trace.
+ * Span ids carry no randomness requirement of their own (unlike trace ids under
+ * W3C Level 2), so a salted counter is sufficient.
+ */
+const SPAN_ID_SALT = BigInt(`0x${randomBytes(8).toString("hex")}`);
+
+/** Apply the process salt to a raw counter. Bijective, so uniqueness within the
+ *  process is preserved exactly. */
+export function saltSpanId(counter: number | bigint): bigint {
+  return (BigInt(counter) ^ SPAN_ID_SALT) & U64_MASK;
+}
+
+/**
+ * Render a span id as exactly 16 lowercase hex characters. An all-zero id is
+ * invalid and is treated as absent rather than emitted, so this returns
+ * `undefined` for zero.
+ */
+export function formatSpanId(value: bigint | number): string | undefined {
+  const masked = BigInt(value) & U64_MASK;
+  if (masked === 0n) return undefined;
+  return masked.toString(16).padStart(SPAN_ID_HEX_LENGTH, "0");
+}
+
+/** Format the salted form of a raw counter — the two steps a record emission
+ *  performs together. */
+export function formatSpanCounter(counter: number | bigint): string | undefined {
+  return formatSpanId(saltSpanId(counter));
+}
+
+/**
+ * Normalize a trace id for emission: exactly 32 lowercase hex characters. Ids
+ * are accepted in either case on ingest and always emitted lowercase. An
+ * all-zero or malformed id is treated as absent.
+ */
+export function normalizeTraceId(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const lowered = value.toLowerCase();
+  if (lowered.length !== TRACE_ID_HEX_LENGTH) return undefined;
+  if (!/^[0-9a-f]+$/.test(lowered)) return undefined;
+  if (/^0+$/.test(lowered)) return undefined;
+  return lowered;
+}
+
+/** The `span_id` counterpart of {@link normalizeTraceId}, for ids arriving as
+ *  hex from an upstream rather than as a local counter. */
+export function normalizeSpanId(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const lowered = value.toLowerCase();
+  if (lowered.length !== SPAN_ID_HEX_LENGTH) return undefined;
+  if (!/^[0-9a-f]+$/.test(lowered)) return undefined;
+  if (/^0+$/.test(lowered)) return undefined;
+  return lowered;
+}
+
+/** A fresh W3C-compatible 16-byte trace id. */
+export function newTraceId(): string {
+  return randomBytes(16).toString("hex");
+}

package/src/logging/to-error-value.ts

@@ -0,0 +1,89 @@
+import type { ErrorValue } from "@telorun/sdk";
+
+/**
+ * Normalize any thrown value into the record's structured error —
+ * `kernel/specs/logging.md` §4.2.
+ *
+ * The `cause` chain is bounded per §6.3 and the truncation is *recorded* rather
+ * than silently applied, so a reader can tell a chain was cut from one that
+ * simply ended.
+ */
+
+const MAX_CAUSE_DEPTH = 10;
+
+export function toErrorValue(thrown: unknown, maxDepth = MAX_CAUSE_DEPTH): ErrorValue {
+  const seen = new Set<unknown>();
+  let depth = 0;
+  let current: unknown = thrown;
+
+  const root = shallowErrorValue(current);
+  let tail = root;
+  seen.add(current);
+
+  while (depth < maxDepth) {
+    const cause = causeOf(current);
+    if (cause === undefined) return root;
+    if (seen.has(cause)) {
+      tail.cause = { type: "ERR_CAUSE_CYCLE", message: "cause chain refers to itself" };
+      return root;
+    }
+    seen.add(cause);
+    const next = shallowErrorValue(cause);
+    tail.cause = next;
+    tail = next;
+    current = cause;
+    depth += 1;
+  }
+
+  if (causeOf(current) !== undefined) {
+    tail.cause = {
+      type: "ERR_CAUSE_CHAIN_TRUNCATED",
+      message: `cause chain truncated at ${maxDepth} entries`,
+    };
+  }
+  return root;
+}
+
+function shallowErrorValue(thrown: unknown): ErrorValue {
+  if (thrown instanceof Error) {
+    const code = (thrown as { code?: unknown }).code;
+    return {
+      type: typeof code === "string" && code.length > 0 ? code : thrown.name,
+      message: thrown.message,
+      ...(thrown.stack ? { stack: thrown.stack } : {}),
+    };
+  }
+
+  if (typeof thrown === "object" && thrown !== null) {
+    const record = thrown as { code?: unknown; name?: unknown; message?: unknown; stack?: unknown };
+    const type =
+      typeof record.code === "string"
+        ? record.code
+        : typeof record.name === "string"
+          ? record.name
+          : "Error";
+    const message =
+      typeof record.message === "string" ? record.message : safeStringify(thrown);
+    return {
+      type,
+      message,
+      ...(typeof record.stack === "string" ? { stack: record.stack } : {}),
+    };
+  }
+
+  return { type: typeof thrown === "string" ? "Error" : typeof thrown, message: String(thrown) };
+}
+
+function causeOf(value: unknown): unknown {
+  if (typeof value !== "object" || value === null) return undefined;
+  const cause = (value as { cause?: unknown }).cause;
+  return cause === undefined || cause === null ? undefined : cause;
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/logging/trace-parent.ts

@@ -0,0 +1,110 @@
+import { normalizeSpanId, normalizeTraceId } from "./span-id.js";
+
+/**
+ * W3C Trace Context propagation — `kernel/specs/logging.md` §7.4 and §7.5.
+ *
+ *     traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ *                  ^version ^trace-id (32 hex)          ^parent-id (16)  ^flags
+ *
+ * Partial adoption of an invalid header is forbidden: a `traceparent` whose
+ * trace-id or parent-id is all zeros is ignored *in full* and a new trace is
+ * started, rather than salvaging whichever half parsed.
+ */
+
+/** Bit 0 — the sampled flag. */
+export const TRACE_FLAG_SAMPLED = 0x01;
+
+/**
+ * Bit 1 — W3C Trace Context **Level 2**'s random trace-id flag, indicating the
+ * right-most 7 bytes of the trace id were chosen randomly, which enables
+ * downstream consistent sampling.
+ *
+ * The bit is *reserved* rather than required to be zero. Level 2 is a Candidate
+ * Recommendation, so a runtime preserves the bit when forwarding an inbound
+ * header but never sets it itself. Requiring it to be zero — the Level 1
+ * reading — would make a conforming runtime corrupt Level 2 traces it merely
+ * forwards.
+ */
+export const TRACE_FLAG_RANDOM = 0x02;
+
+/** Bits 0–1 survive an outgoing request; bits 2–7 are zeroed (§7.5). */
+const OUTGOING_FLAG_MASK = TRACE_FLAG_SAMPLED | TRACE_FLAG_RANDOM;
+
+const TRACESTATE_MAX_MEMBERS = 32;
+const TRACESTATE_MAX_LENGTH = 512;
+
+export interface TraceContext {
+  traceId: string;
+  parentSpanId: string;
+  traceFlags: number;
+  /** Propagated unmodified, or absent when it could not be parsed. Never
+   *  partially rewritten. */
+  traceState?: string;
+}
+
+/**
+ * Parse an inbound `traceparent`. Returns `undefined` when the header is absent,
+ * malformed, or carries an all-zero id — in every one of those cases the caller
+ * starts a fresh trace rather than adopting part of it.
+ */
+export function parseTraceParent(
+  traceparent: string | undefined,
+  tracestate?: string | undefined,
+): TraceContext | undefined {
+  if (!traceparent) return undefined;
+
+  const parts = traceparent.trim().split("-");
+  if (parts.length < 4) return undefined;
+
+  const [version, rawTraceId, rawParentId, rawFlags] = parts as [string, string, string, string];
+
+  // Version `ff` is invalid; unknown future versions are parsed leniently, which
+  // the spec permits so long as the four known fields validate.
+  if (!/^[0-9a-f]{2}$/.test(version) || version === "ff") return undefined;
+
+  const traceId = normalizeTraceId(rawTraceId);
+  const parentSpanId = normalizeSpanId(rawParentId);
+  if (!traceId || !parentSpanId) return undefined;
+
+  if (!/^[0-9a-f]{2}$/.test(rawFlags)) return undefined;
+  const traceFlags = Number.parseInt(rawFlags, 16);
+
+  return {
+    traceId,
+    parentSpanId,
+    traceFlags,
+    traceState: parseTraceState(tracestate),
+  };
+}
+
+/**
+ * `tracestate` is propagated unmodified. One that cannot be parsed is discarded
+ * in full rather than partially rewritten, so a downstream never receives a
+ * mangled header that looks valid.
+ */
+export function parseTraceState(tracestate: string | undefined): string | undefined {
+  if (!tracestate) return undefined;
+  const trimmed = tracestate.trim();
+  if (trimmed.length === 0) return undefined;
+  if (trimmed.length > TRACESTATE_MAX_LENGTH) return undefined;
+  const members = trimmed.split(",");
+  if (members.length > TRACESTATE_MAX_MEMBERS) return undefined;
+  for (const member of members) {
+    if (member.trim().length === 0) continue;
+    if (!member.includes("=")) return undefined;
+  }
+  return trimmed;
+}
+
+/**
+ * Serialize an outgoing `traceparent`. Bits 2–7 of the flags are zeroed; bit 1
+ * survives only because it arrived that way on an inbound header.
+ */
+export function formatTraceParent(context: {
+  traceId: string;
+  spanId: string;
+  traceFlags?: number;
+}): string {
+  const flags = (context.traceFlags ?? 0) & OUTGOING_FLAG_MASK;
+  return `00-${context.traceId}-${context.spanId}-${flags.toString(16).padStart(2, "0")}`;
+}

package/src/manifest-schemas.ts

@@ -82,6 +82,11 @@ const KNOWN_CAPABILITIES = [
   "Telo.Provider",
   "Telo.Type",
   "Telo.Mount",
+  // A record-stream destination the runtime writes to directly rather than
+  // through `ctx.invoke` — per-record dispatch is far too slow for a logging hot
+  // path, and dispatch emits trace events, so routing logs through it would
+  // generate telemetry from inside the telemetry path. See kernel/specs/logging.md §10.
+  "Telo.Sink",
 ] as const;
 
 /** Rule 8: `throws:` is only meaningful on Telo.Invocable or Telo.Runnable.
@@ -115,6 +120,13 @@ export const ResourceDefinitionSchema = {
       properties: { capability: { const: "Telo.Mount" } },
       ...forbidThrows,
     },
+    {
+      // A sink is written to directly, never dispatched, so a thrown error is a
+      // boot-time failure rather than a structured runtime error for a caller.
+      required: ["capability"],
+      properties: { capability: { const: "Telo.Sink" } },
+      ...forbidThrows,
+    },
     // Unknown/absent capability: open schema for third-party extensibility
     {
       not: {