@telorun/sdk 0.2.5 → 0.2.7

package/src/ref.ts

@@ -0,0 +1,61 @@
+import type { ResourceInstance } from "./resource-instance.js";
+
+/** Marker type for x-telo-ref fields. Carries the live instance type at the TypeScript level;
+ *  at runtime this field holds `{ kind, name }` until Phase 5 injection replaces it.
+ *  T is a phantom type — any capability interface (Invocable, Runnable, …) or ResourceInstance. */
+export interface KindRef<T = ResourceInstance> {
+  readonly kind: string;
+  readonly name: string;
+  readonly __type?: T;
+}
+
+/** Marker type for x-telo-scope fields. Has no runtime value — used only as a discriminant
+ *  for Injected<T> to transform the field to ScopeHandle. */
+export interface ScopeRef {
+  readonly __scope: true;
+}
+
+/** Gives a controller access to the resources initialized within a scope. */
+export interface ScopeContext {
+  /** Returns the initialized instance for the given name.
+   *  Throws synchronously if the name was not declared in the scope —
+   *  this is always a programming error; all scope members are statically
+   *  validated in Phase 3 before the kernel ever reaches runtime. */
+  getInstance(name: string): ResourceInstance;
+}
+
+/** Returned by Phase 5 injection in place of an x-telo-scope manifest array.
+ *  The controller calls run() to open the scope, execute work, and tear it down. */
+export interface ScopeHandle {
+  run<T>(fn: (scope: ScopeContext) => Promise<T>): Promise<T>;
+}
+
+/** Transforms the raw config shape into the controller's view:
+ *  - KindRef<U>   → U        (live instance, injected by Phase 5)
+ *  - KindRef<U>[] → U[]      (live instances, injected by Phase 5)
+ *  - ScopeRef     → ScopeHandle
+ *  - everything else is unchanged */
+export type Injected<T> = {
+  [K in keyof T]: T[K] extends KindRef<infer U>
+    ? U
+    : T[K] extends KindRef<infer U>[]
+      ? U[]
+      : NonNullable<T[K]> extends ScopeRef
+        ? ScopeHandle | Exclude<T[K], ScopeRef>
+        : T[K];
+};
+
+/** Returns a schema node that emits `x-telo-ref` for buildReferenceFieldMap and carries
+ *  KindRef<T> as its TypeScript type. For TypeBox schemas use Type.Unsafe<KindRef<T>>(Ref(...)).
+ *
+ *  @param ref Canonical ref string: "namespace/module-name#TypeName" or "kernel#TypeName" */
+export const Ref = <T = ResourceInstance>(ref: string): KindRef<T> =>
+  ({ "x-telo-ref": ref } as unknown as KindRef<T>);
+
+/** Returns a schema node that emits `x-telo-scope` for buildReferenceFieldMap and carries
+ *  ScopeRef as its TypeScript type. For TypeBox schemas use Type.Unsafe<ScopeRef>(Scope(...)).
+ *
+ *  @param visibilityPath JSON Pointer(s) (RFC 6901) declaring where x-telo-ref slots within
+ *                        this field can resolve to scoped resources. */
+export const Scope = (visibilityPath: string | string[]): ScopeRef =>
+  ({ "x-telo-scope": visibilityPath } as unknown as ScopeRef);

package/src/resource-context.ts

@@ -8,6 +8,12 @@ export interface DataValidator {
   isValid(data: any): boolean;
 }
 
+export interface TypeRule {
+  condition: string;
+  code: string;
+  message?: string;
+}
+
 export class NoopValidator implements DataValidator {
   isValid() {
     return true;
@@ -18,30 +24,35 @@ export class NoopValidator implements DataValidator {
   }
 }
 
+export type ParsedArgs = Partial<Record<string, string | boolean | string[]>> & { _: string[] };
+
 export interface ResourceContext extends ControllerContext {
+  readonly args: ParsedArgs;
   acquireHold(reason?: string): () => void;
   emitEvent(event: string, payload?: any): Promise<void>;
-  invoke(kind: string, name: string, ...args: any[]): Promise<any>;
+  invoke<TInputs>(kind: string, name: string, inputs: TInputs, options?: any): Promise<any>;
   run(kind: string, name: string): Promise<void>;
   getResources(kind: string): RuntimeResource[];
   getResourcesByName(kind: string, name: string): RuntimeResource | null;
   registerManifest(resource: any): void;
   spawnChildContext(): EvaluationContext;
+  transientChild(context: Record<string, any>): EvaluationContext;
   withManifests<T>(manifests: any[], fn: () => T): T;
   resolveChildren(resource: any, resourceName?: string): { kind: string; name: string };
   validateSchema(value: any, schema: any): void;
   createSchemaValidator(schema: any): DataValidator;
   registerSchema(name: string, schema: object): void;
   lookupSchema(name: string): object | undefined;
+  registerTypeRules(name: string, rules: TypeRule[]): void;
+  lookupTypeRules(name: string): TypeRule[] | undefined;
+  /** Resolve a type reference (name string or inline schema) to a DataValidator. */
+  createTypeValidator(typeRef: string | Record<string, any> | undefined): DataValidator;
   registerController(moduleName: string, kindName: string, controllerInstance: any): Promise<void>;
   registerDefinition(definition: any): void;
   registerModuleImport(alias: string, targetModule: string, kinds: string[]): void;
-  registerCapability(name: string, schema?: Record<string, any>): void;
-  isCapabilityRegistered(name: string): boolean;
-  getCapabilitySchema(name: string): Record<string, any> | null | undefined;
   teardownResource(kind: string, name: string): Promise<void>;
-  moduleContext: ModuleContext;
-  stdin: NodeJS.ReadableStream;
-  stdout: NodeJS.WritableStream;
-  stderr: NodeJS.WritableStream;
+  readonly moduleContext: ModuleContext;
+  readonly stdin: NodeJS.ReadableStream;
+  readonly stdout: NodeJS.WritableStream;
+  readonly stderr: NodeJS.WritableStream;
 }

package/src/resource-instance.ts

@@ -1,15 +1,12 @@
-import { ResourceContext } from "./resource-context.js";
+import type { Invocable } from "./capabilities/invokable.js";
+import type { Runnable } from "./capabilities/runnable.js";
+import type { ResourceContext } from "./resource-context.js";
 
-export type ResourceInstance = {
-  init?(ctx?: ResourceContext): Promise<void>;
-  run?(): void | Promise<void>;
-  invoke?(input: any): any | Promise<any>;
-  teardown?(): void | Promise<void>;
-
-  /**
-   * Optional method for debugging/snapshots
-   * Called when taking runtime state snapshots
-   * Should return serializable state data specific to this resource
-   */
-  snapshot?(): Record<string, any> | Promise<Record<string, any>>;
-};
+export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<
+  Invocable<TInput, TOutput>
+> &
+  Partial<Runnable> & {
+    init?(ctx?: ResourceContext): Promise<void>;
+    teardown?(): void | Promise<void>;
+    snapshot?(): Record<string, any> | Promise<Record<string, any>>;
+  };

package/src/runtime-error.ts

@@ -1,3 +1,11 @@
+export interface RuntimeDiagnostic {
+  severity?: "error" | "warning";
+  message: string;
+  resource?: string;
+  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"
@@ -9,4 +17,10 @@ export type RuntimeErrorCode =
   | "ERR_DUPLICATE_RESOURCE"
   | "ERR_EXECUTION_FAILED"
   | "ERR_INVALID_VALUE"
-  | "ERR_VISIBILITY_DENIED";
+  | "ERR_VISIBILITY_DENIED"
+  | "ERR_MANIFEST_VALIDATION_FAILED"
+  | "ERR_CIRCULAR_DEPENDENCY"
+  | "ERR_SCOPE_RESOURCE_NOT_FOUND"
+  | "ERR_TYPE_NOT_FOUND"
+  | "ERR_TYPE_VALIDATION_FAILED"
+  | (string & {});

package/src/types.ts

@@ -2,7 +2,7 @@ import { ControllerContext } from "./controller-context.js";
 import { ResourceContext } from "./resource-context.js";
 import { ResourceInstance } from "./resource-instance.js";
 import { ResourceManifest } from "./resource-manifest.js";
-import { RuntimeErrorCode } from "./runtime-error.js";
+import { RuntimeDiagnostic, RuntimeErrorCode } from "./runtime-error.js";
 import { RuntimeResource } from "./runtime-resource.js";
 
 export interface KernelContext {
@@ -14,17 +14,15 @@ export interface ExecContext {
   [key: string]: any;
 }
 
-export type ResourceCapability = string;
-
 export interface ResourceDefinition {
   kind: string;
   metadata: {
     name: string;
     module: string;
   };
-  schema: Record<string, any>; // JSON Schema
-  capabilities: ResourceCapability[];
-  events?: string[];
+  /** JSON Schema for the resource's compile-time configuration fields. */
+  schema?: Record<string, any>;
+  capability?: string;
   controllers?: Array<{
     runtime: string;
     entry: string;
@@ -44,19 +42,30 @@ export interface ControllerDefinition {
 
 /**
  * Controller instance - runtime representation of a controller that handles resource instances.
+ *
+ * TResource - the typed shape of the resource manifest (compile-time config)
+ * TInput    - the typed shape of invoke() inputs (runtime)
+ * TOutput   - the typed shape of invoke() outputs (runtime)
  */
-export interface ControllerInstance {
+export interface ControllerInstance<
+  TResource extends ResourceManifest = ResourceManifest,
+  TInput = Record<string, any>,
+  TOutput = any,
+> {
   execute?(name: string, inputs: any, ctx: ExecContext): Promise<any>;
-  compile?(
-    resource: ResourceManifest,
-    ctx: ResourceContext,
-  ): RuntimeResource | Promise<RuntimeResource>;
+  compile?(resource: TResource, ctx: ResourceContext): RuntimeResource | Promise<RuntimeResource>;
   register?(ctx: ControllerContext): void | Promise<void>;
   create?(
-    resource: ResourceManifest,
+    resource: TResource,
     ctx: ResourceContext,
-  ): ResourceInstance | null | Promise<ResourceInstance | null>;
-  schema: any;
+  ): ResourceInstance<TInput, TOutput> | null | Promise<ResourceInstance<TInput, TOutput> | null>;
+  schema?: any;
+  /** CLI argument spec. Keys are arg names; values define type, alias, and description. */
+  args?: Record<string, { type: "string" | "boolean"; alias?: string; description?: string }>;
+  /** Type reference for invoke() inputs — name string or inline type definition. */
+  inputType?: string | Record<string, any>;
+  /** Type reference for invoke() outputs — name string or inline type definition. */
+  outputType?: string | Record<string, any>;
 }
 
 export interface Kernel {
@@ -76,6 +85,7 @@ export class RuntimeError extends Error {
   constructor(
     public code: RuntimeErrorCode,
     message: string,
+    public diagnostics?: RuntimeDiagnostic[],
   ) {
     super(message);
     this.name = "RuntimeError";