@telorun/kernel 0.62.0 → 0.64.0

package/src/runtime-seam.ts

@@ -0,0 +1,230 @@
+import {
+  Loader,
+  StaticAnalyzer,
+  flattenForAnalyzer,
+  type AnalysisDiagnostic,
+  type ManifestSource,
+} from "@telorun/analyzer";
+import {
+  Stream,
+  type RuntimeCheckOptions,
+  type RuntimeCheckResult,
+  type CheckDiagnostic,
+  type CheckDiagnosticSeverity,
+  type RuntimeRun,
+  type RuntimeRunOptions,
+  type RuntimeSeam,
+} from "@telorun/sdk";
+import { Writable } from "stream";
+import { nodeCelHandlers } from "./cel-handlers.js";
+import type { Kernel } from "./kernel.js";
+import { defaultTransportRegistry } from "./transports/transport-registry.js";
+
+/**
+ * How many unconsumed chunks a channel holds before it stops acknowledging the
+ * child's writes.
+ *
+ * This is a courtesy, **not a memory bound**, and the distinction matters enough
+ * to state: withholding a `Writable`'s `_write` callback only moves subsequent
+ * chunks into the stream's own internal buffer, which is unbounded, and a
+ * controller writing to `ctx.stdout` does not await `drain`. So a child whose
+ * output nobody reads still grows the host's memory. What actually bounds it is
+ * `RuntimeRun.cancel()` — stopping the child, rather than hoping it stops
+ * producing. What the high-water mark does buy is that a *slow* consumer sees
+ * chunks handed over in order without the channel racing ahead of it.
+ */
+const CHANNEL_HIGH_WATER_MARK = 256;
+
+interface PendingChunk {
+  text: string;
+  /** The child's `_write` callback, held back once the channel is over its
+   *  high-water mark and released when a consumer takes the chunk. */
+  release?: () => void;
+}
+
+/**
+ * One direction of a child's output: a `Writable` the child kernel writes to,
+ * and the {@link Stream} the caller reads. Bridges Node's stream model to the
+ * SDK's without either side seeing the other's — `RuntimeSeam` has no
+ * `Writable` in it, and the child kernel has no `Stream` in it.
+ */
+class OutputChannel {
+  #queue: PendingChunk[] = [];
+  #waiters: Array<(result: IteratorResult<string>) => void> = [];
+  #ended = false;
+
+  readonly writable: Writable = new Writable({
+    write: (chunk: Buffer | string, _encoding, callback) => {
+      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      this.#push(text, callback);
+    },
+  });
+
+  readonly stream: Stream<string> = new Stream<string>({
+    [Symbol.asyncIterator]: () => ({
+      next: () => this.#next(),
+    }),
+  });
+
+  /** No more output is coming. Wakes every waiter with a terminal result, so a
+   *  `for await` over the stream completes rather than hanging on a child that
+   *  has already exited. */
+  end(): void {
+    this.#ended = true;
+    while (this.#waiters.length > 0) {
+      this.#waiters.shift()!({ value: undefined, done: true });
+    }
+  }
+
+  #push(text: string, callback: () => void): void {
+    const waiter = this.#waiters.shift();
+    if (waiter) {
+      waiter({ value: text, done: false });
+      callback();
+      return;
+    }
+    if (this.#queue.length >= CHANNEL_HIGH_WATER_MARK) {
+      this.#queue.push({ text, release: callback });
+      return;
+    }
+    this.#queue.push({ text });
+    callback();
+  }
+
+  async #next(): Promise<IteratorResult<string>> {
+    const pending = this.#queue.shift();
+    if (pending) {
+      pending.release?.();
+      return { value: pending.text, done: false };
+    }
+    if (this.#ended) return { value: undefined, done: true };
+    return new Promise<IteratorResult<string>>((resolve) => this.#waiters.push(resolve));
+  }
+}
+
+const SEVERITY_NAMES: Record<number, CheckDiagnosticSeverity> = {
+  1: "error",
+  2: "warning",
+  3: "info",
+  4: "hint",
+};
+
+/** Flatten an analyzer finding to the seam's plain-data shape. Severity becomes
+ *  a name because the integer is an LSP protocol detail, and this contract is
+ *  read by kernels that speak no LSP. An unlabelled severity is an error: the
+ *  analyzer's own default, and the safe reading for a caller gating on it. */
+function toCheckDiagnostic(diagnostic: AnalysisDiagnostic): CheckDiagnostic {
+  return {
+    code: String(diagnostic.code ?? ""),
+    message: diagnostic.message,
+    severity: SEVERITY_NAMES[diagnostic.severity ?? 1] ?? "error",
+    source: diagnostic.source,
+    line: diagnostic.range?.start?.line,
+    column: diagnostic.range?.start?.character,
+  };
+}
+
+/**
+ * The kernel's implementation of the SDK's {@link RuntimeSeam} — run a manifest,
+ * analyze a manifest — built over the `Kernel`, `Loader` and `StaticAnalyzer`
+ * this kernel already owns.
+ *
+ * Isolation is this class's choice, not the caller's: today a child `Kernel` in
+ * the same process, later a subprocess. That is what keeps process-global host
+ * state (the `process.env` guardrail is additive across in-process kernels) an
+ * implementation detail rather than something a module author has to know.
+ */
+export class KernelRuntimeSeam implements RuntimeSeam {
+  constructor(private readonly kernel: Kernel) {}
+
+  async run(source: string, options?: RuntimeRunOptions): Promise<RuntimeRun> {
+    // Import here rather than at module scope: `resource-context.ts` imports this
+    // file to construct the seam and `kernel.ts` imports *that*, so a top-level
+    // import of `Kernel` here would close the cycle. The dynamic import resolves
+    // after both modules are evaluated.
+    const { Kernel: ChildKernel } = await import("./kernel.js");
+    const stdout = new OutputChannel();
+    const stderr = new OutputChannel();
+
+    const child = new ChildKernel({
+      env: options?.env ?? this.kernel.env,
+      stdout: stdout.writable,
+      stderr: stderr.writable,
+      sources: [...this.kernel.injectedSources],
+      registryUrl: this.kernel.registryUrl,
+    });
+
+    // A child that fails to load is not an exception on this side: the caller
+    // asked to run a manifest and the answer is "it exited non-zero, here is
+    // why", which keeps both failure modes on one path. `start()` tears the
+    // child down in its own `finally`, so this only has to close the channels.
+    const exitCode = (async () => {
+      try {
+        await child.load(source);
+        await child.start();
+        return child.exitCode;
+      } catch (err) {
+        stderr.writable.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return child.exitCode === 0 ? 1 : child.exitCode;
+      } finally {
+        stdout.end();
+        stderr.end();
+      }
+    })();
+
+    let cancelled: Promise<void> | undefined;
+    const cancel = (reason = "cancelled"): Promise<void> => {
+      // Idempotent: repeated calls await the first teardown rather than starting
+      // another. `teardown()` is itself idempotent, but a second `forceIdle()`
+      // against a kernel already unwinding buys nothing.
+      cancelled ??= (async () => {
+        // Cancel the boot run first so an in-flight target observes it, then
+        // release `waitForIdle` so `start()`'s own `finally` performs the
+        // teardown — the same path a SIGINT takes. Awaiting `exitCode` is what
+        // makes "resolves when teardown has completed" true.
+        child.cancel(reason);
+        child.forceIdle();
+        await exitCode;
+      })();
+      return cancelled;
+    };
+
+    return { stdout: stdout.stream, stderr: stderr.stream, exitCode, cancel };
+  }
+
+  async check(source: string, options?: RuntimeCheckOptions): Promise<RuntimeCheckResult> {
+    // A fresh loader over this kernel's own resolution chain — the transports it
+    // was configured with plus whatever sources were injected — so `check()`
+    // resolves an import exactly as a run of the same manifest would. Fresh
+    // rather than the kernel's own loader because a checked manifest is often
+    // deliberately broken and has no business entering the running kernel's
+    // parse cache.
+    const loader = new Loader(defaultTransportRegistry(this.kernel.registryUrl).sources(), {
+      celHandlers: nodeCelHandlers,
+    });
+    for (const injected of this.kernel.injectedSources) {
+      loader.register(injected as ManifestSource);
+    }
+
+    let manifests;
+    try {
+      const graph = await loader.loadGraph(source, {
+        desugarImports: options?.desugarImports ?? true,
+      });
+      if (graph.errors.length > 0) throw graph.errors[0].error;
+      manifests = flattenForAnalyzer(graph);
+    } catch (err) {
+      // A graph that would not load is an answer, not a failure of the call —
+      // "this manifest does not load, and here is the reason" is precisely what
+      // a caller asked for. Throwing would force every caller to re-express the
+      // distinction in a catch.
+      return {
+        diagnostics: [],
+        loadError: err instanceof Error ? err.message : String(err),
+      };
+    }
+
+    const diagnostics = new StaticAnalyzer({ celHandlers: nodeCelHandlers }).analyze(manifests);
+    return { diagnostics: diagnostics.map(toCheckDiagnostic) };
+  }
+}

package/dist/logging/record-buffer.d.ts

@@ -1,24 +0,0 @@
-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 declare class RecordBuffer {
-    #private;
-    constructor(policy: SinkBufferPolicy, onDrop: () => void);
-    get size(): number;
-    get isFull(): boolean;
-    push(record: LogRecord): void;
-    /** Take everything buffered, leaving the buffer empty. */
-    drain(): LogRecord[];
-}
-//# sourceMappingURL=record-buffer.d.ts.map

package/dist/logging/record-buffer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"record-buffer.d.ts","sourceRoot":"","sources":["../../src/logging/record-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;;gBASX,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,IAAI;IAMxD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAiB7B,0DAA0D;IAC1D,KAAK,IAAI,SAAS,EAAE;CAerB"}

package/dist/logging/record-buffer.js

@@ -1,78 +0,0 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _RecordBuffer_instances, _RecordBuffer_capacity, _RecordBuffer_policy, _RecordBuffer_onDrop, _RecordBuffer_items, _RecordBuffer_head, _RecordBuffer_compact;
-/**
- * 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 {
-    constructor(policy, onDrop) {
-        _RecordBuffer_instances.add(this);
-        _RecordBuffer_capacity.set(this, void 0);
-        _RecordBuffer_policy.set(this, void 0);
-        _RecordBuffer_onDrop.set(this, void 0);
-        _RecordBuffer_items.set(this, []);
-        /** Index of the oldest record, so `drop_old` evicts in O(1) instead of
-         *  shifting the whole array on every overflow. */
-        _RecordBuffer_head.set(this, 0);
-        __classPrivateFieldSet(this, _RecordBuffer_capacity, Math.max(1, policy.buffer), "f");
-        __classPrivateFieldSet(this, _RecordBuffer_policy, policy, "f");
-        __classPrivateFieldSet(this, _RecordBuffer_onDrop, onDrop, "f");
-    }
-    get size() {
-        return __classPrivateFieldGet(this, _RecordBuffer_items, "f").length - __classPrivateFieldGet(this, _RecordBuffer_head, "f");
-    }
-    get isFull() {
-        return this.size >= __classPrivateFieldGet(this, _RecordBuffer_capacity, "f");
-    }
-    push(record) {
-        if (this.isFull) {
-            if (__classPrivateFieldGet(this, _RecordBuffer_policy, "f").onFull === "drop_old") {
-                __classPrivateFieldSet(this, _RecordBuffer_head, __classPrivateFieldGet(this, _RecordBuffer_head, "f") + 1, "f");
-                __classPrivateFieldGet(this, _RecordBuffer_instances, "m", _RecordBuffer_compact).call(this);
-            }
-            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.
-                __classPrivateFieldGet(this, _RecordBuffer_onDrop, "f").call(this);
-                return;
-            }
-            __classPrivateFieldGet(this, _RecordBuffer_onDrop, "f").call(this);
-        }
-        __classPrivateFieldGet(this, _RecordBuffer_items, "f").push(record);
-    }
-    /** Take everything buffered, leaving the buffer empty. */
-    drain() {
-        const drained = __classPrivateFieldGet(this, _RecordBuffer_head, "f") === 0 ? __classPrivateFieldGet(this, _RecordBuffer_items, "f") : __classPrivateFieldGet(this, _RecordBuffer_items, "f").slice(__classPrivateFieldGet(this, _RecordBuffer_head, "f"));
-        __classPrivateFieldSet(this, _RecordBuffer_items, [], "f");
-        __classPrivateFieldSet(this, _RecordBuffer_head, 0, "f");
-        return drained;
-    }
-}
-_RecordBuffer_capacity = new WeakMap(), _RecordBuffer_policy = new WeakMap(), _RecordBuffer_onDrop = new WeakMap(), _RecordBuffer_items = new WeakMap(), _RecordBuffer_head = new WeakMap(), _RecordBuffer_instances = new WeakSet(), _RecordBuffer_compact = function _RecordBuffer_compact() {
-    // Reclaim the consumed prefix once it dominates the array, so a long-lived
-    // ring does not grow its backing store without bound.
-    if (__classPrivateFieldGet(this, _RecordBuffer_head, "f") > 32 && __classPrivateFieldGet(this, _RecordBuffer_head, "f") * 2 >= __classPrivateFieldGet(this, _RecordBuffer_items, "f").length) {
-        __classPrivateFieldSet(this, _RecordBuffer_items, __classPrivateFieldGet(this, _RecordBuffer_items, "f").slice(__classPrivateFieldGet(this, _RecordBuffer_head, "f")), "f");
-        __classPrivateFieldSet(this, _RecordBuffer_head, 0, "f");
-    }
-};
-//# sourceMappingURL=record-buffer.js.map

package/dist/logging/record-buffer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"record-buffer.js","sourceRoot":"","sources":["../../src/logging/record-buffer.ts"],"names":[],"mappings":";;;;;;;;;;;;AAGA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,YAAY;IASvB,YAAY,MAAwB,EAAE,MAAkB;;QAR/C,yCAAkB;QAClB,uCAA0B;QAC1B,uCAAoB;QAC7B,8BAAsB,EAAE,EAAC;QACzB;0DACkD;QAClD,6BAAQ,CAAC,EAAC;QAGR,uBAAA,IAAI,0BAAa,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,MAAA,CAAC;QAC5C,uBAAA,IAAI,wBAAW,MAAM,MAAA,CAAC;QACtB,uBAAA,IAAI,wBAAW,MAAM,MAAA,CAAC;IACxB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,uBAAA,IAAI,2BAAO,CAAC,MAAM,GAAG,uBAAA,IAAI,0BAAM,CAAC;IACzC,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,IAAI,IAAI,uBAAA,IAAI,8BAAU,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,MAAiB;QACpB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,uBAAA,IAAI,4BAAQ,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBACvC,yGAAc,CAAC,MAAA,CAAC;gBAChB,uBAAA,IAAI,sDAAS,MAAb,IAAI,CAAW,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,uEAAuE;gBACvE,iEAAiE;gBACjE,2CAA2C;gBAC3C,uBAAA,IAAI,4BAAQ,MAAZ,IAAI,CAAU,CAAC;gBACf,OAAO;YACT,CAAC;YACD,uBAAA,IAAI,4BAAQ,MAAZ,IAAI,CAAU,CAAC;QACjB,CAAC;QACD,uBAAA,IAAI,2BAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED,0DAA0D;IAC1D,KAAK;QACH,MAAM,OAAO,GAAG,uBAAA,IAAI,0BAAM,KAAK,CAAC,CAAC,CAAC,CAAC,uBAAA,IAAI,2BAAO,CAAC,CAAC,CAAC,uBAAA,IAAI,2BAAO,CAAC,KAAK,CAAC,uBAAA,IAAI,0BAAM,CAAC,CAAC;QAC/E,uBAAA,IAAI,uBAAU,EAAE,MAAA,CAAC;QACjB,uBAAA,IAAI,sBAAS,CAAC,MAAA,CAAC;QACf,OAAO,OAAO,CAAC;IACjB,CAAC;CAUF;;IAPG,2EAA2E;IAC3E,sDAAsD;IACtD,IAAI,uBAAA,IAAI,0BAAM,GAAG,EAAE,IAAI,uBAAA,IAAI,0BAAM,GAAG,CAAC,IAAI,uBAAA,IAAI,2BAAO,CAAC,MAAM,EAAE,CAAC;QAC5D,uBAAA,IAAI,uBAAU,uBAAA,IAAI,2BAAO,CAAC,KAAK,CAAC,uBAAA,IAAI,0BAAM,CAAC,MAAA,CAAC;QAC5C,uBAAA,IAAI,sBAAS,CAAC,MAAA,CAAC;IACjB,CAAC;AACH,CAAC"}

package/src/logging/record-buffer.ts

@@ -1,72 +0,0 @@
-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;
-    }
-  }
-}