@telorun/sdk 0.10.0 → 1.0.0

package/README.md

@@ -8,10 +8,6 @@ The Node.js SDK provides the authoring surface for Telo modules. It defines the
 - **Context types** for accessing the kernel, registry, and events.
 - **Shared primitives** used by Telo modules and tooling.
 
-## Status
-
-Early prototype. APIs and contracts are still evolving. The API surface - including YAML shapes - may change at any time without notice.
-
 ## When to Use It
 
 Use the SDK when building or extending Telo modules. It is not the kernel itself; it is the contract layer that keeps module behavior consistent and predictable.
@@ -73,5 +69,5 @@ throws:
 ## Related Docs
 
 - Kernel overview: [kernel/README.md](../../kernel/README.md)
-- Built‑in modules: [modules/](../../modules/)
+- Built‑in modules: [Standard Library](../../modules/README.md)
 - SDKs index: [sdk/README.md](../README.md)

package/dist/capabilities/provider.d.ts

@@ -1,4 +1,4 @@
-export interface Provider {
-    init(): Promise<void>;
+export interface Provider<TOutput = unknown> {
+    provide(): Promise<TOutput>;
 }
 //# sourceMappingURL=provider.d.ts.map

package/dist/capabilities/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/capabilities/provider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/capabilities/provider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ,CAAC,OAAO,GAAG,OAAO;IACzC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7B"}

package/dist/resource-instance.d.ts

@@ -1,7 +1,8 @@
 import type { Invocable } from "./capabilities/invokable.js";
+import type { Provider } from "./capabilities/provider.js";
 import type { Runnable } from "./capabilities/runnable.js";
 import type { ResourceContext } from "./resource-context.js";
-export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<Invocable<TInput, TOutput>> & Partial<Runnable> & {
+export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<Invocable<TInput, TOutput>> & Partial<Runnable> & Partial<Provider<TOutput>> & {
     init?(ctx?: ResourceContext): Promise<void>;
     teardown?(): void | Promise<void>;
     snapshot?(): Record<string, any> | Promise<Record<string, any>>;

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

@@ -1 +1 @@
-{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GAAG;IAClB,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;CACjE,CAAC"}
+{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG;IAC3B,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;CACjE,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/package.json

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

package/src/capabilities/provider.ts

@@ -1,3 +1,3 @@
-export interface Provider {
-  init(): Promise<void>;
+export interface Provider<TOutput = unknown> {
+  provide(): Promise<TOutput>;
 }

package/src/resource-instance.ts

@@ -1,11 +1,13 @@
 import type { Invocable } from "./capabilities/invokable.js";
+import type { Provider } from "./capabilities/provider.js";
 import type { Runnable } from "./capabilities/runnable.js";
 import type { ResourceContext } from "./resource-context.js";
 
 export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<
   Invocable<TInput, TOutput>
 > &
-  Partial<Runnable> & {
+  Partial<Runnable> &
+  Partial<Provider<TOutput>> & {
     init?(ctx?: ResourceContext): Promise<void>;
     teardown?(): void | Promise<void>;
     snapshot?(): Record<string, any> | Promise<Record<string, any>>;

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 };