@telorun/sdk 0.7.0 → 0.11.1

package/README.md

@@ -1,7 +1,3 @@
----
-description: "Node.js SDK: module interfaces, context types, and shared primitives; distinguishes operational vs domain failures via InvokeError"
----
-
 # Telo SDK (Node.js)
 
 The Node.js SDK provides the authoring surface for Telo modules. It defines the shared contracts (types and lifecycle interfaces) that modules use to plug into the kernel, so module code stays consistent across implementations.

package/dist/resource-context.d.ts

@@ -59,6 +59,19 @@ export interface ResourceContext extends ControllerContext {
      * `runtime:`). Consumers should treat undefined as "auto."
      */
     getControllerPolicy(): ControllerPolicy | undefined;
+    /**
+     * URL of the entry manifest the kernel is running, or `undefined` if the
+     * kernel hasn't loaded a manifest yet. Stable for the lifetime of the
+     * kernel process once set; identical across every resource regardless of
+     * which imported library defined it. Controllers (and the controller-loader)
+     * anchor per-manifest install roots here so a single `node_modules` tree
+     * and one realpath for `@telorun/sdk` are shared by every controller in
+     * the process. The `undefined` case shows up only for callers that bypass
+     * `Kernel.load()` (e.g. early in test setup); resource controllers always
+     * see a defined value because their `init()` runs after `load()` has
+     * recorded it.
+     */
+    getEntryUrl(): string | undefined;
     /** Load a single module (its own file + `include`d partials). Use this when
      *  you need just the declaring file's manifests. */
     loadModule(url: string, options?: LoadOptions): Promise<ResourceManifest[]>;

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-error.d.ts

@@ -7,5 +7,5 @@ export interface RuntimeDiagnostic {
     code?: string;
 }
 /** Well-known kernel error codes. User-defined codes (e.g. from Type.JsonSchema rules) are also valid. */
-export type RuntimeErrorCode = "ERR_RESOURCE_NOT_FOUND" | "ERR_RESOURCE_NOT_RUNNABLE" | "ERR_CONTROLLER_NOT_FOUND" | "ERR_CONTROLLER_INVALID" | "ERR_RESOURCE_INITIALIZATION_FAILED" | "ERR_RESOURCE_NOT_INVOKABLE" | "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED" | "ERR_DUPLICATE_RESOURCE" | "ERR_EXECUTION_FAILED" | "ERR_INVALID_VALUE" | "ERR_VISIBILITY_DENIED" | "ERR_MANIFEST_VALIDATION_FAILED" | "ERR_CIRCULAR_DEPENDENCY" | "ERR_SCOPE_RESOURCE_NOT_FOUND" | "ERR_TYPE_NOT_FOUND" | "ERR_TYPE_VALIDATION_FAILED" | (string & {});
+export type RuntimeErrorCode = "ERR_RESOURCE_NOT_FOUND" | "ERR_RESOURCE_NOT_RUNNABLE" | "ERR_CONTROLLER_NOT_FOUND" | "ERR_CONTROLLER_INVALID" | "ERR_RESOURCE_INITIALIZATION_FAILED" | "ERR_RESOURCE_NOT_INVOKABLE" | "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED" | "ERR_DUPLICATE_RESOURCE" | "ERR_EXECUTION_FAILED" | "ERR_INVALID_VALUE" | "ERR_VISIBILITY_DENIED" | "ERR_MANIFEST_VALIDATION_FAILED" | "ERR_CIRCULAR_DEPENDENCY" | "ERR_SCOPE_RESOURCE_NOT_FOUND" | "ERR_TYPE_NOT_FOUND" | "ERR_TYPE_VALIDATION_FAILED" | "ERR_KERNEL_STATE_INVALID" | (string & {});
 //# sourceMappingURL=runtime-error.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-error.d.ts","sourceRoot":"","sources":["../src/runtime-error.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,0GAA0G;AAC1G,MAAM,MAAM,gBAAgB,GACxB,wBAAwB,GACxB,2BAA2B,GAC3B,0BAA0B,GAC1B,wBAAwB,GACxB,oCAAoC,GACpC,4BAA4B,GAC5B,uCAAuC,GACvC,wBAAwB,GACxB,sBAAsB,GACtB,mBAAmB,GACnB,uBAAuB,GACvB,gCAAgC,GAChC,yBAAyB,GACzB,8BAA8B,GAC9B,oBAAoB,GACpB,4BAA4B,GAC5B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC"}
+{"version":3,"file":"runtime-error.d.ts","sourceRoot":"","sources":["../src/runtime-error.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,0GAA0G;AAC1G,MAAM,MAAM,gBAAgB,GACxB,wBAAwB,GACxB,2BAA2B,GAC3B,0BAA0B,GAC1B,wBAAwB,GACxB,oCAAoC,GACpC,4BAA4B,GAC5B,uCAAuC,GACvC,wBAAwB,GACxB,sBAAsB,GACtB,mBAAmB,GACnB,uBAAuB,GACvB,gCAAgC,GAChC,yBAAyB,GACzB,8BAA8B,GAC9B,oBAAoB,GACpB,4BAA4B,GAC5B,0BAA0B,GAC1B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC"}

package/dist/stream.d.ts

@@ -11,6 +11,18 @@
  * resulting value a real-class constructor that cel-js can register and
  * recognize, so `${{ steps.X.result.output }}` evaluations pass through cleanly.
  *
+ * Singleton across sdk copies: cel-js identifies registered types by
+ * constructor identity (`v.constructor === RegisteredCtor`). The kernel and
+ * any npm-loaded controller can — and routinely do — resolve `@telorun/sdk`
+ * to different installs (workspace vs `.telo/npm/<hash>/...`), so two `Stream`
+ * classes with the same shape but different identity would silently break
+ * stream-typed CEL evaluations with "Unsupported type: Stream". The first
+ * `@telorun/sdk` copy to load registers its `Stream` class on `globalThis`
+ * under a stable `Symbol.for("@telorun/sdk:Stream")` key; later copies discard
+ * their local declaration at export time and re-export the registered one.
+ * Every Stream value in the process shares one constructor regardless of
+ * install topology — no build artifact or `file:` symlink required.
+ *
  * The companion analyzer registers `Stream` as a CEL object type with no
  * fields — terminal access (passing the value through) succeeds, member access
  * (`result.output.text`, `result.output[0]`) raises a CEL error at runtime,
@@ -24,9 +36,14 @@
  * patterns work without unwrapping. Internally it forwards `Symbol.asyncIterator`
  * to the underlying iterable.
  */
-export declare class Stream<T = unknown> implements AsyncIterable<T> {
-    private readonly source;
-    constructor(source: AsyncIterable<T>);
-    [Symbol.asyncIterator](): AsyncIterator<T>;
+interface Stream<T = unknown> extends AsyncIterable<T> {
 }
+declare const LocalStream: {
+    new <T = unknown>(source: AsyncIterable<T>): {
+        "__#private@#source": AsyncIterable<T>;
+        [Symbol.asyncIterator](): AsyncIterator<T>;
+    };
+};
+declare const Stream: typeof LocalStream;
+export { Stream };
 //# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,MAAM,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAErD,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;CAG3C"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,UAAU,MAAM,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;CAAG;AAOzD,QAAA,MAAM,WAAW;SAAgB,CAAC,oBAMZ,aAAa,CAAC,CAAC,CAAC;8BAF3B,aAAa,CAAC,CAAC,CAAC;kCAMC,aAAa,CAAC,CAAC,CAAC;;CAG3C,CAAC;AAUF,QAAA,MAAM,MAAM,EAAE,OAAO,WAA0D,CAAC;AAMhF,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/stream.js

@@ -11,6 +11,18 @@
  * resulting value a real-class constructor that cel-js can register and
  * recognize, so `${{ steps.X.result.output }}` evaluations pass through cleanly.
  *
+ * Singleton across sdk copies: cel-js identifies registered types by
+ * constructor identity (`v.constructor === RegisteredCtor`). The kernel and
+ * any npm-loaded controller can — and routinely do — resolve `@telorun/sdk`
+ * to different installs (workspace vs `.telo/npm/<hash>/...`), so two `Stream`
+ * classes with the same shape but different identity would silently break
+ * stream-typed CEL evaluations with "Unsupported type: Stream". The first
+ * `@telorun/sdk` copy to load registers its `Stream` class on `globalThis`
+ * under a stable `Symbol.for("@telorun/sdk:Stream")` key; later copies discard
+ * their local declaration at export time and re-export the registered one.
+ * Every Stream value in the process shares one constructor regardless of
+ * install topology — no build artifact or `file:` symlink required.
+ *
  * The companion analyzer registers `Stream` as a CEL object type with no
  * fields — terminal access (passing the value through) succeeds, member access
  * (`result.output.text`, `result.output[0]`) raises a CEL error at runtime,
@@ -24,12 +36,34 @@
  * patterns work without unwrapping. Internally it forwards `Symbol.asyncIterator`
  * to the underlying iterable.
  */
-export class Stream {
-    source;
+// Value binding (private): the class declaration that supplies the runtime
+// implementation. Written as a named class expression so `.name === "Stream"`
+// — debuggers, stack traces, and `Object.prototype.toString` all see "Stream",
+// not the const name. The inner `Stream` identifier is only visible inside
+// the class body (for self-reference); it does not shadow the outer interface.
+const LocalStream = class Stream {
+    // ECMAScript private field rather than TS `private readonly` — the latter
+    // shows up in the inferred type signature, which TS then refuses to export
+    // through an anonymous class expression (TS4094).
+    #source;
     constructor(source) {
-        this.source = source;
+        this.#source = source;
     }
     [Symbol.asyncIterator]() {
-        return this.source[Symbol.asyncIterator]();
+        return this.#source[Symbol.asyncIterator]();
     }
-}
+};
+const STREAM_KEY = Symbol.for("@telorun/sdk:Stream");
+const globalSlot = globalThis;
+if (!(STREAM_KEY in globalSlot))
+    globalSlot[STREAM_KEY] = LocalStream;
+// The exported value: whichever Stream class won the globalThis race (first
+// sdk copy to import this module). Later copies discard their `LocalStream`
+// at export time and route through the winner — keeping constructor identity
+// stable across the kernel/controller realm boundary.
+const Stream = globalSlot[STREAM_KEY];
+// `export { Stream }` re-exports the value binding (the const above) and the
+// type binding (the interface above) under the same name — TypeScript treats
+// value/type as separate namespaces, so a consumer's `import { Stream }`
+// receives both `new Stream(...)` and `Stream<T>`.
+export { Stream };

package/dist/types.d.ts

@@ -83,12 +83,48 @@ export interface ControllerInstance<TResource extends ResourceManifest = Resourc
 }
 export interface Kernel {
     load(url: string): Promise<void>;
+    /**
+     * Boot: initialize resources without running targets. Returns when every
+     * resource is initialized and the kernel is ready to accept `invoke()`
+     * calls. Throws ERR_KERNEL_STATE_INVALID if called twice or after teardown.
+     */
+    boot(): Promise<void>;
+    /**
+     * Run the manifest's `targets` (Telo.Service / Telo.Runnable instances).
+     * Throws ERR_KERNEL_STATE_INVALID if called before `boot()` completes, after
+     * teardown, or a second time.
+     */
+    runTargets(): Promise<void>;
+    /**
+     * Tear down every initialized resource. Idempotent — second call is a no-op
+     * and does not re-emit Kernel.Stopping / Kernel.Stopped. Tolerates partial
+     * state (a boot() that threw mid-init still cleans up).
+     */
+    teardown(): Promise<void>;
+    /**
+     * Invoke a Telo.Invocable resource by name. Throws ERR_KERNEL_STATE_INVALID
+     * if called before boot() or after teardown.
+     */
+    invoke<TInputs = any, TOutput = any>(ref: string | {
+        kind: string;
+        name: string;
+    }, inputs: TInputs): Promise<TOutput>;
+    /**
+     * Convenience: boot → runTargets → waitForIdle → teardown, with teardown
+     * always running via finally so init-time failures still tear down.
+     */
     start(): Promise<void>;
     acquireHold(reason?: string): () => void;
     waitForIdle(): Promise<void>;
+    /**
+     * Force-resolve a pending `waitForIdle()` even when holds are still active.
+     * Used by external signal handlers (SIGINT/SIGTERM) so graceful exit can
+     * proceed past `await kernel.waitForIdle()`. Does not tear down — call
+     * `teardown()` for cleanup.
+     */
+    forceIdle(): void;
     requestExit(code: number): void;
     readonly exitCode: number;
-    shutdown(): void;
 }
 export declare class RuntimeError extends Error {
     code: RuntimeErrorCode;

package/dist/types.d.ts.map

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

package/package.json

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

package/src/resource-context.ts

@@ -70,6 +70,19 @@ export interface ResourceContext extends ControllerContext {
    * `runtime:`). Consumers should treat undefined as "auto."
    */
   getControllerPolicy(): ControllerPolicy | undefined;
+  /**
+   * URL of the entry manifest the kernel is running, or `undefined` if the
+   * kernel hasn't loaded a manifest yet. Stable for the lifetime of the
+   * kernel process once set; identical across every resource regardless of
+   * which imported library defined it. Controllers (and the controller-loader)
+   * anchor per-manifest install roots here so a single `node_modules` tree
+   * and one realpath for `@telorun/sdk` are shared by every controller in
+   * the process. The `undefined` case shows up only for callers that bypass
+   * `Kernel.load()` (e.g. early in test setup); resource controllers always
+   * see a defined value because their `init()` runs after `load()` has
+   * recorded it.
+   */
+  getEntryUrl(): string | undefined;
   /** Load a single module (its own file + `include`d partials). Use this when
    *  you need just the declaring file's manifests. */
   loadModule(url: string, options?: LoadOptions): Promise<ResourceManifest[]>;

package/src/runtime-error.ts

@@ -25,4 +25,5 @@ export type RuntimeErrorCode =
   | "ERR_SCOPE_RESOURCE_NOT_FOUND"
   | "ERR_TYPE_NOT_FOUND"
   | "ERR_TYPE_VALIDATION_FAILED"
+  | "ERR_KERNEL_STATE_INVALID"
   | (string & {});

package/src/stream.ts

@@ -11,6 +11,18 @@
  * resulting value a real-class constructor that cel-js can register and
  * recognize, so `${{ steps.X.result.output }}` evaluations pass through cleanly.
  *
+ * Singleton across sdk copies: cel-js identifies registered types by
+ * constructor identity (`v.constructor === RegisteredCtor`). The kernel and
+ * any npm-loaded controller can — and routinely do — resolve `@telorun/sdk`
+ * to different installs (workspace vs `.telo/npm/<hash>/...`), so two `Stream`
+ * classes with the same shape but different identity would silently break
+ * stream-typed CEL evaluations with "Unsupported type: Stream". The first
+ * `@telorun/sdk` copy to load registers its `Stream` class on `globalThis`
+ * under a stable `Symbol.for("@telorun/sdk:Stream")` key; later copies discard
+ * their local declaration at export time and re-export the registered one.
+ * Every Stream value in the process shares one constructor regardless of
+ * install topology — no build artifact or `file:` symlink required.
+ *
  * The companion analyzer registers `Stream` as a CEL object type with no
  * fields — terminal access (passing the value through) succeeds, member access
  * (`result.output.text`, `result.output[0]`) raises a CEL error at runtime,
@@ -24,10 +36,43 @@
  * patterns work without unwrapping. Internally it forwards `Symbol.asyncIterator`
  * to the underlying iterable.
  */
-export class Stream<T = unknown> implements AsyncIterable<T> {
-  constructor(private readonly source: AsyncIterable<T>) {}
+
+// Type binding: `Stream<T>` as written by consumers (`let s: Stream<number>`)
+// resolves to this interface. The class below also conforms to it.
+interface Stream<T = unknown> extends AsyncIterable<T> {}
+
+// Value binding (private): the class declaration that supplies the runtime
+// implementation. Written as a named class expression so `.name === "Stream"`
+// — debuggers, stack traces, and `Object.prototype.toString` all see "Stream",
+// not the const name. The inner `Stream` identifier is only visible inside
+// the class body (for self-reference); it does not shadow the outer interface.
+const LocalStream = class Stream<T = unknown> implements AsyncIterable<T> {
+  // ECMAScript private field rather than TS `private readonly` — the latter
+  // shows up in the inferred type signature, which TS then refuses to export
+  // through an anonymous class expression (TS4094).
+  #source: AsyncIterable<T>;
+
+  constructor(source: AsyncIterable<T>) {
+    this.#source = source;
+  }
 
   [Symbol.asyncIterator](): AsyncIterator<T> {
-    return this.source[Symbol.asyncIterator]();
+    return this.#source[Symbol.asyncIterator]();
   }
-}
+};
+
+const STREAM_KEY = Symbol.for("@telorun/sdk:Stream");
+const globalSlot = globalThis as Record<symbol, unknown>;
+if (!(STREAM_KEY in globalSlot)) globalSlot[STREAM_KEY] = LocalStream;
+
+// The exported value: whichever Stream class won the globalThis race (first
+// sdk copy to import this module). Later copies discard their `LocalStream`
+// at export time and route through the winner — keeping constructor identity
+// stable across the kernel/controller realm boundary.
+const Stream: typeof LocalStream = globalSlot[STREAM_KEY] as typeof LocalStream;
+
+// `export { Stream }` re-exports the value binding (the const above) and the
+// type binding (the interface above) under the same name — TypeScript treats
+// value/type as separate namespaces, so a consumer's `import { Stream }`
+// receives both `new Stream(...)` and `Stream<T>`.
+export { Stream };

package/src/types.ts

@@ -94,15 +94,48 @@ export interface ControllerInstance<
 
 export interface Kernel {
   load(url: string): Promise<void>;
+  /**
+   * Boot: initialize resources without running targets. Returns when every
+   * resource is initialized and the kernel is ready to accept `invoke()`
+   * calls. Throws ERR_KERNEL_STATE_INVALID if called twice or after teardown.
+   */
+  boot(): Promise<void>;
+  /**
+   * Run the manifest's `targets` (Telo.Service / Telo.Runnable instances).
+   * Throws ERR_KERNEL_STATE_INVALID if called before `boot()` completes, after
+   * teardown, or a second time.
+   */
+  runTargets(): Promise<void>;
+  /**
+   * Tear down every initialized resource. Idempotent — second call is a no-op
+   * and does not re-emit Kernel.Stopping / Kernel.Stopped. Tolerates partial
+   * state (a boot() that threw mid-init still cleans up).
+   */
+  teardown(): Promise<void>;
+  /**
+   * Invoke a Telo.Invocable resource by name. Throws ERR_KERNEL_STATE_INVALID
+   * if called before boot() or after teardown.
+   */
+  invoke<TInputs = any, TOutput = any>(
+    ref: string | { kind: string; name: string },
+    inputs: TInputs,
+  ): Promise<TOutput>;
+  /**
+   * Convenience: boot → runTargets → waitForIdle → teardown, with teardown
+   * always running via finally so init-time failures still tear down.
+   */
   start(): Promise<void>;
   acquireHold(reason?: string): () => void;
   waitForIdle(): Promise<void>;
+  /**
+   * Force-resolve a pending `waitForIdle()` even when holds are still active.
+   * Used by external signal handlers (SIGINT/SIGTERM) so graceful exit can
+   * proceed past `await kernel.waitForIdle()`. Does not tear down — call
+   * `teardown()` for cleanup.
+   */
+  forceIdle(): void;
   requestExit(code: number): void;
   readonly exitCode: number;
-  // teardownResource(module: string, kind: string, name: string): Promise<void>;
-  // getSourceFiles(): string[];
-  // reloadSource(sourcePath: string): Promise<void>;
-  shutdown(): void;
 }
 
 export class RuntimeError extends Error {