@telorun/sdk 0.62.0 → 0.63.0

package/dist/index.d.ts

@@ -22,6 +22,8 @@ export * from "./contract-errors.js";
 export * from "./invoke-error.js";
 export * from "./log-record.js";
 export * from "./log-sink.js";
+export * from "./record-buffer.js";
+export * from "./runtime-seam.js";
 export * from "./log-severity.js";
 export * from "./logger.js";
 export * from "./network-fetch.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,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,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,sBAAsB,CAAC;AACrC,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,qBAAqB,CAAC;AACpC,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,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,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,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -22,6 +22,8 @@ export * from "./contract-errors.js";
 export * from "./invoke-error.js";
 export * from "./log-record.js";
 export * from "./log-sink.js";
+export * from "./record-buffer.js";
+export * from "./runtime-seam.js";
 export * from "./log-severity.js";
 export * from "./logger.js";
 export * from "./network-fetch.js";

package/dist/record-buffer.d.ts

@@ -0,0 +1,29 @@
+import type { LogRecord } from "./log-record.js";
+import type { SinkBufferPolicy } from "./log-sink.js";
+/**
+ * The bounded buffer every asynchronous sink composes — `kernel/specs/logging.md`
+ * §10.3.
+ *
+ * It lives beside the sink contract for the same reason that contract does: a
+ * third-party sink is an ordinary module, so the piece it composes to honour
+ * `on_full` must be on the module-author surface rather than behind a
+ * kernel-internal import.
+ *
+ * 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/record-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-buffer.d.ts","sourceRoot":"","sources":["../src/record-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;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/record-buffer.js

@@ -0,0 +1,69 @@
+/**
+ * The bounded buffer every asynchronous sink composes — `kernel/specs/logging.md`
+ * §10.3.
+ *
+ * It lives beside the sink contract for the same reason that contract does: a
+ * third-party sink is an ordinary module, so the piece it composes to honour
+ * `on_full` must be on the module-author surface rather than behind a
+ * kernel-internal import.
+ *
+ * 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 {
+    #capacity;
+    #policy;
+    #onDrop;
+    #items = [];
+    /** 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, onDrop) {
+        this.#capacity = Math.max(1, policy.buffer);
+        this.#policy = policy;
+        this.#onDrop = onDrop;
+    }
+    get size() {
+        return this.#items.length - this.#head;
+    }
+    get isFull() {
+        return this.size >= this.#capacity;
+    }
+    push(record) {
+        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() {
+        const drained = this.#head === 0 ? this.#items : this.#items.slice(this.#head);
+        this.#items = [];
+        this.#head = 0;
+        return drained;
+    }
+    #compact() {
+        // 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/dist/resource-context.d.ts

@@ -9,6 +9,7 @@ import type { KindRef } from "./ref.js";
 import { ResourceInstance } from "./resource-instance.js";
 import { ResourceManifest } from "./resource-manifest.js";
 import { RuntimeResource } from "./runtime-resource.js";
+import type { RuntimeSeam } from "./runtime-seam.js";
 export interface LoadOptions {
     /** When true, `${{ }}` templates are replaced with CompiledValue wrappers
      *  so they can be evaluated at runtime. Leave unset for static analysis. */
@@ -210,6 +211,13 @@ export interface ResourceContext extends ControllerContext {
      * {@link log}.
      */
     readonly logging: LoggingHost;
+    /**
+     * The host's own manifest machinery — run a manifest, analyze a manifest.
+     * See {@link RuntimeSeam}. A controller that needs either reaches it here
+     * rather than importing the kernel or the analyzer, so a published module
+     * binds to a versioned contract instead of to whatever kernel loads it.
+     */
+    readonly runtime: RuntimeSeam;
     readonly moduleContext: ModuleContext;
     readonly env: Record<string, string | undefined>;
     readonly stdin: NodeJS.ReadableStream;

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

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

package/dist/runtime-seam.d.ts

@@ -0,0 +1,108 @@
+import type { Stream } from "./stream.js";
+/**
+ * The host's own manifest machinery, exposed to a controller as `ctx.runtime`:
+ * **run a manifest**, **analyze a manifest**.
+ *
+ * It lives on the module-author surface because the modules that need it are
+ * ordinary modules — `test` runs a child manifest, `assert`'s `Manifest` kind
+ * analyzes one — and reaching into a kernel-internal import to do that would make
+ * kernel internals an unversioned ABI between a published artifact and whatever
+ * kernel loads it. It is deliberately not test-shaped: a workflow engine running
+ * sub-manifests, a supervisor, a hub validating a published module and CI tooling
+ * all want one half or the other.
+ *
+ * Every shape crossing this boundary is plain serializable data or a
+ * {@link Stream}, so no kernel or analyzer class is part of the contract and a
+ * kernel in any language can implement it. **Isolation is the kernel's choice** —
+ * an in-process child kernel today, a subprocess later — which is what keeps
+ * process-global host state an implementation detail rather than something a
+ * caller has to reason about.
+ */
+export interface RuntimeSeam {
+    /**
+     * Load and start `source` as a child manifest, isolated from the caller's.
+     *
+     * Resolves once the child has **started**, not once it has finished, so the
+     * caller can consume its output while it runs; completion is
+     * {@link RuntimeRun.exitCode}. A child that fails to load is not an exception
+     * here — it settles `exitCode` non-zero with the failure written to `stderr`,
+     * so a caller handles both failure modes in one place.
+     *
+     * **The caller owns the child's lifetime.** Drain both streams, or stop it with
+     * {@link RuntimeRun.cancel}; a child nobody reads and nobody stops keeps
+     * producing, and its output accumulates in the host's memory.
+     */
+    run(source: string, options?: RuntimeRunOptions): Promise<RuntimeRun>;
+    /**
+     * Run the static-analysis pass over `source` and its import graph without
+     * instantiating anything. Never throws for a manifest that fails to load —
+     * that is {@link RuntimeCheckResult.loadError}, which is an answer, not an
+     * error.
+     */
+    check(source: string, options?: RuntimeCheckOptions): Promise<RuntimeCheckResult>;
+}
+export interface RuntimeRunOptions {
+    /** Host environment the child binds its `variables:` / `secrets:` / `ports:`
+     *  from. Omitted means the caller's own — a child never inherits more than it
+     *  is handed. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * A started child manifest.
+ *
+ * Output is a stream rather than a captured string because the two useful
+ * behaviours — forward it live, keep it to print on failure — are the caller's
+ * to choose, and only one of them survives a value produced at the end. A caller
+ * that just wants the text drains the stream itself.
+ *
+ * A stream does **not** by itself bound the host's memory: an unread stream still
+ * accumulates whatever the child writes. What bounds it is {@link cancel} — stop
+ * the child, rather than hoping it stops producing.
+ */
+export interface RuntimeRun {
+    readonly stdout: Stream<string>;
+    readonly stderr: Stream<string>;
+    /** Settles when the child has finished — including after {@link cancel}. Both
+     *  streams have ended by then. */
+    readonly exitCode: Promise<number>;
+    /**
+     * Stop the child and tear it down.
+     *
+     * On the contract from the start rather than added later: termination is the
+     * first thing a supervisor or a workflow engine running an open-ended
+     * sub-manifest needs, and it is also the only bound on an unread child's
+     * output. Idempotent, and safe after the child has already finished.
+     *
+     * Resolves when teardown has completed, so a caller that must know the child
+     * released its resources — ports, connections, files — can await it.
+     */
+    cancel(reason?: string): Promise<void>;
+}
+export interface RuntimeCheckOptions {
+    /** Expand each module document's inline `imports:` map into synthetic
+     *  `Telo.Import` manifests before analysis, so a manifest using inline imports
+     *  analyzes the way it runs. */
+    desugarImports?: boolean;
+}
+/** Severity as a name rather than the LSP integer: the integer is a protocol
+ *  detail of one editor transport, and this contract is read by a Rust or Go
+ *  kernel too. */
+export type CheckDiagnosticSeverity = "error" | "warning" | "info" | "hint";
+/** One analyzer finding, flattened to data. Positions are zero-based, matching
+ *  the analyzer's own range model. */
+export interface CheckDiagnostic {
+    code: string;
+    message: string;
+    severity: CheckDiagnosticSeverity;
+    /** URL of the manifest the finding is in, when the analyzer located one. */
+    source?: string;
+    line?: number;
+    column?: number;
+}
+export interface RuntimeCheckResult {
+    diagnostics: CheckDiagnostic[];
+    /** Set when the import graph could not be loaded at all, in which case
+     *  `diagnostics` is empty — there was nothing to analyze. */
+    loadError?: string;
+}
+//# sourceMappingURL=runtime-seam.d.ts.map

package/dist/runtime-seam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-seam.d.ts","sourceRoot":"","sources":["../src/runtime-seam.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtE;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACnF;AAED,MAAM,WAAW,iBAAiB;IAChC;;qBAEiB;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC;sCACkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,mBAAmB;IAClC;;oCAEgC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;kBAEkB;AAClB,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5E;sCACsC;AACtC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,uBAAuB,CAAC;IAClC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B;iEAC6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/runtime-seam.js

@@ -0,0 +1 @@
+export {};

package/package.json

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

package/src/index.ts

@@ -22,6 +22,8 @@ export * from "./contract-errors.js";
 export * from "./invoke-error.js";
 export * from "./log-record.js";
 export * from "./log-sink.js";
+export * from "./record-buffer.js";
+export * from "./runtime-seam.js";
 export * from "./log-severity.js";
 export * from "./logger.js";
 export * from "./network-fetch.js";

package/src/record-buffer.ts

@@ -0,0 +1,77 @@
+import type { LogRecord } from "./log-record.js";
+import type { SinkBufferPolicy } from "./log-sink.js";
+
+/**
+ * The bounded buffer every asynchronous sink composes — `kernel/specs/logging.md`
+ * §10.3.
+ *
+ * It lives beside the sink contract for the same reason that contract does: a
+ * third-party sink is an ordinary module, so the piece it composes to honour
+ * `on_full` must be on the module-author surface rather than behind a
+ * kernel-internal import.
+ *
+ * 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/resource-context.ts

@@ -9,6 +9,7 @@ import type { KindRef } from "./ref.js";
 import { ResourceInstance } from "./resource-instance.js";
 import { ResourceManifest } from "./resource-manifest.js";
 import { RuntimeResource } from "./runtime-resource.js";
+import type { RuntimeSeam } from "./runtime-seam.js";
 
 export interface LoadOptions {
   /** When true, `${{ }}` templates are replaced with CompiledValue wrappers
@@ -227,6 +228,13 @@ export interface ResourceContext extends ControllerContext {
    * {@link log}.
    */
   readonly logging: LoggingHost;
+  /**
+   * The host's own manifest machinery — run a manifest, analyze a manifest.
+   * See {@link RuntimeSeam}. A controller that needs either reaches it here
+   * rather than importing the kernel or the analyzer, so a published module
+   * binds to a versioned contract instead of to whatever kernel loads it.
+   */
+  readonly runtime: RuntimeSeam;
   readonly moduleContext: ModuleContext;
   readonly env: Record<string, string | undefined>;
   readonly stdin: NodeJS.ReadableStream;

package/src/runtime-seam.ts

@@ -0,0 +1,114 @@
+import type { Stream } from "./stream.js";
+
+/**
+ * The host's own manifest machinery, exposed to a controller as `ctx.runtime`:
+ * **run a manifest**, **analyze a manifest**.
+ *
+ * It lives on the module-author surface because the modules that need it are
+ * ordinary modules — `test` runs a child manifest, `assert`'s `Manifest` kind
+ * analyzes one — and reaching into a kernel-internal import to do that would make
+ * kernel internals an unversioned ABI between a published artifact and whatever
+ * kernel loads it. It is deliberately not test-shaped: a workflow engine running
+ * sub-manifests, a supervisor, a hub validating a published module and CI tooling
+ * all want one half or the other.
+ *
+ * Every shape crossing this boundary is plain serializable data or a
+ * {@link Stream}, so no kernel or analyzer class is part of the contract and a
+ * kernel in any language can implement it. **Isolation is the kernel's choice** —
+ * an in-process child kernel today, a subprocess later — which is what keeps
+ * process-global host state an implementation detail rather than something a
+ * caller has to reason about.
+ */
+export interface RuntimeSeam {
+  /**
+   * Load and start `source` as a child manifest, isolated from the caller's.
+   *
+   * Resolves once the child has **started**, not once it has finished, so the
+   * caller can consume its output while it runs; completion is
+   * {@link RuntimeRun.exitCode}. A child that fails to load is not an exception
+   * here — it settles `exitCode` non-zero with the failure written to `stderr`,
+   * so a caller handles both failure modes in one place.
+   *
+   * **The caller owns the child's lifetime.** Drain both streams, or stop it with
+   * {@link RuntimeRun.cancel}; a child nobody reads and nobody stops keeps
+   * producing, and its output accumulates in the host's memory.
+   */
+  run(source: string, options?: RuntimeRunOptions): Promise<RuntimeRun>;
+  /**
+   * Run the static-analysis pass over `source` and its import graph without
+   * instantiating anything. Never throws for a manifest that fails to load —
+   * that is {@link RuntimeCheckResult.loadError}, which is an answer, not an
+   * error.
+   */
+  check(source: string, options?: RuntimeCheckOptions): Promise<RuntimeCheckResult>;
+}
+
+export interface RuntimeRunOptions {
+  /** Host environment the child binds its `variables:` / `secrets:` / `ports:`
+   *  from. Omitted means the caller's own — a child never inherits more than it
+   *  is handed. */
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * A started child manifest.
+ *
+ * Output is a stream rather than a captured string because the two useful
+ * behaviours — forward it live, keep it to print on failure — are the caller's
+ * to choose, and only one of them survives a value produced at the end. A caller
+ * that just wants the text drains the stream itself.
+ *
+ * A stream does **not** by itself bound the host's memory: an unread stream still
+ * accumulates whatever the child writes. What bounds it is {@link cancel} — stop
+ * the child, rather than hoping it stops producing.
+ */
+export interface RuntimeRun {
+  readonly stdout: Stream<string>;
+  readonly stderr: Stream<string>;
+  /** Settles when the child has finished — including after {@link cancel}. Both
+   *  streams have ended by then. */
+  readonly exitCode: Promise<number>;
+  /**
+   * Stop the child and tear it down.
+   *
+   * On the contract from the start rather than added later: termination is the
+   * first thing a supervisor or a workflow engine running an open-ended
+   * sub-manifest needs, and it is also the only bound on an unread child's
+   * output. Idempotent, and safe after the child has already finished.
+   *
+   * Resolves when teardown has completed, so a caller that must know the child
+   * released its resources — ports, connections, files — can await it.
+   */
+  cancel(reason?: string): Promise<void>;
+}
+
+export interface RuntimeCheckOptions {
+  /** Expand each module document's inline `imports:` map into synthetic
+   *  `Telo.Import` manifests before analysis, so a manifest using inline imports
+   *  analyzes the way it runs. */
+  desugarImports?: boolean;
+}
+
+/** Severity as a name rather than the LSP integer: the integer is a protocol
+ *  detail of one editor transport, and this contract is read by a Rust or Go
+ *  kernel too. */
+export type CheckDiagnosticSeverity = "error" | "warning" | "info" | "hint";
+
+/** One analyzer finding, flattened to data. Positions are zero-based, matching
+ *  the analyzer's own range model. */
+export interface CheckDiagnostic {
+  code: string;
+  message: string;
+  severity: CheckDiagnosticSeverity;
+  /** URL of the manifest the finding is in, when the analyzer located one. */
+  source?: string;
+  line?: number;
+  column?: number;
+}
+
+export interface RuntimeCheckResult {
+  diagnostics: CheckDiagnostic[];
+  /** Set when the import graph could not be loaded at all, in which case
+   *  `diagnostics` is empty — there was nothing to analyze. */
+  loadError?: string;
+}