@telorun/kernel 0.60.0 → 0.61.0

package/src/invocation-contract-binding.ts

@@ -0,0 +1,392 @@
+import {
+  type ContractDirection,
+  defaultBearingPaths,
+  effectiveContractField,
+  type DefResolver,
+  withStreamPropertiesSkipped,
+} from "@telorun/analyzer";
+import type { ResourceDefinition, ResourceInstance, ResourceManifest } from "@telorun/sdk";
+import {
+  ERR_CONTRACT_UNRESOLVABLE,
+  ERR_INPUT_INVALID,
+  ERR_OUTPUT_INVALID,
+  InvokeError,
+} from "@telorun/sdk";
+
+/**
+ * Binds a resource's resolved invocation contract to its dispatch entry points,
+ * at the moment the kernel produces the instance.
+ *
+ * A contract is only a guarantee if it cannot be dispatched around, and most
+ * consumers never reach the kernel's dispatch chokepoint: Phase-5 injection puts
+ * the live instance straight into a consumer's config object, so `Ai.Agent`
+ * reads `this.resource.model` and calls `model.invoke(...)` in hand. Enforcing at
+ * a handoff would mean enforcing at every handoff — Phase-5 injection,
+ * `ctx.resolveRef`, scope-handle resolution, the template controller's direct
+ * dispatch, `ctx.invoke`'s target lookup — and one forgotten site silently
+ * reopens the hole.
+ *
+ * So the kernel binds instead, at `_createInstance`: its single production site.
+ * Every consumer, on every path, then holds an instance whose dispatch already
+ * enforces. Binding rather than wrapping is also what keeps the rest a
+ * non-problem — there is one object, so controller-specific members are
+ * genuinely its own, the prototype chain (and `instanceof` across the SDK realm
+ * boundary) is untouched, and `stripCompiledValues` / `detachSnapshotValue` see
+ * exactly the object they always saw. It is the same in-place technique the
+ * kernel already uses to fold detached-task draining into `teardown()` and
+ * runtime CEL expansion into `invoke()`.
+ *
+ * Consequence, stated rather than left to be discovered: the bound `invoke`
+ * shadows the controller's, so a controller calling `this.invoke()` internally
+ * goes through its own contract.
+ */
+
+/** Compiles a JSON Schema to a validator. The kernel's `SchemaValidator` runs
+ *  with `useDefaults`, so validating also fills declared defaults. */
+export interface ContractValidatorFactory {
+  (typeRef: unknown): { validate(value: unknown): void };
+  /** Resolves a type field to its JSON Schema, for the schema-level decisions
+   *  (stream skipping, default paths) a compiled validator can't answer. */
+  schemaOf(typeRef: unknown): Record<string, any> | undefined;
+  /** Resolves a `$ref` to the registered schema it names, so the schema walks
+   *  can see through the reference form the compiled validator keeps intact. */
+  resolveRef(ref: string): Record<string, any> | undefined;
+  /** Compiles an adjusted schema while keeping the CEL `rules:` registered under
+   *  a named type — the one path that survives stripping a stream property from
+   *  a named contract without abandoning its invariants. */
+  withRules(name: string | undefined, schema: Record<string, any>): { validate(value: unknown): void };
+}
+
+export interface BoundContract {
+  direction: ContractDirection;
+  validate(value: unknown): void;
+  /** Paths a default can be written to — how far the caller's value must be
+   *  copied before validation runs. Empty when the contract declares none. */
+  defaultPaths(): string[][];
+}
+
+const CONTRACT_ERROR: Record<ContractDirection, string> = {
+  inputType: ERR_INPUT_INVALID,
+  outputType: ERR_OUTPUT_INVALID,
+};
+
+/**
+ * Resolve one direction of a resource's contract to a bound validator.
+ *
+ * The declaration is layered instance-manifest → nearest along `extends` (see
+ * `effectiveContractField` — nearest wins, contracts never merge), then compiled.
+ *
+ * A NAMED reference (`inputType: RequestShape`, or a `!ref` to a type) is
+ * compiled by name so it keeps the CEL `rules:` registered alongside it, which a
+ * plain schema copy would drop. Everything else is compiled from the resolved
+ * schema — inline `{kind, schema}` and raw forms carry no rules, and resolving
+ * first is what lets a `{ $ref: "telo://Self/X" }` contract compile at all
+ * (`resolveTypeSchema` follows it through the kernel's registry, which AJV
+ * cannot).
+ *
+ * The resolved schema is stripped of `x-telo-stream` properties first: a live
+ * `Stream` in a declared slot is not data to be traversed, the same defect as
+ * `stripCompiledValues` walking a live instance in a ref slot. Streams travel in
+ * both directions (`Codec.Encoder` marks `input` on its `inputType` and requires
+ * it), so the skip is not one-directional.
+ *
+ * WHICH declaration applies is decided here, at create time — that is a fact
+ * about the manifest. COMPILING it is deferred to first dispatch and memoized: a
+ * contract may reference a named `telo#Type` whose `Type.JsonSchema` resource
+ * initializes later in the same multi-pass loop, and resolving it eagerly would
+ * make every contract-declaring kind depend on type-registration order. Nothing
+ * can dispatch before the loop finishes, so first-use is always late enough.
+ */
+/** True when a type field names a registered `telo#Type` — a bare name, or the
+ *  `{kind, name}` object a `!ref` normalizes to. Only these carry CEL `rules:`,
+ *  so only these are worth compiling by name rather than from their schema. */
+function isNamedTypeReference(declared: unknown): boolean {
+  if (typeof declared === "string") return true;
+  if (!declared || typeof declared !== "object") return false;
+  const ref = declared as Record<string, unknown>;
+  return typeof ref.name === "string" && !(ref.schema && typeof ref.schema === "object");
+}
+
+export function resolveBoundContract(
+  direction: ContractDirection,
+  manifest: ResourceManifest,
+  definition: ResourceDefinition | undefined,
+  resolveDef: DefResolver,
+  factory: ContractValidatorFactory,
+): BoundContract | undefined {
+  const own = (manifest as unknown as Record<string, unknown>)[direction];
+  const declared =
+    own !== undefined && own !== null
+      ? own
+      : effectiveContractField(definition, resolveDef, direction);
+  if (declared === undefined || declared === null) return undefined;
+
+  let compiled: { validate(value: unknown): void } | undefined;
+  let paths: string[][] | undefined;
+
+  const resolve = (): { validate(value: unknown): void } => {
+    if (compiled !== undefined) return compiled;
+    const schema = factory.schemaOf(declared);
+    if (!schema) {
+      // A declared contract that resolves to nothing is a manifest fault — a
+      // named type that never registered — and it MUST NOT degrade to
+      // "unvalidated". Silently disabling enforcement is the failure mode
+      // nobody notices: every later call passes because nothing is checking.
+      throw new InvokeError(
+        ERR_CONTRACT_UNRESOLVABLE,
+        `declared \`${direction}\` could not be resolved to a schema: ${describeDeclaration(declared)}. ` +
+          `The type is not registered, so the contract cannot be enforced.`,
+      );
+    }
+    const stripped = withStreamPropertiesSkipped(schema, factory.resolveRef);
+    paths = defaultBearingPaths(stripped, factory.resolveRef);
+    // Compile by NAME whenever the declaration is one, so the type's CEL
+    // `rules:` are composed in — including when a stream had to be stripped, in
+    // which case the stream-bearing properties are dropped from the schema the
+    // named validator sees rather than the reference being abandoned.
+    compiled = !isNamedTypeReference(declared)
+      ? factory(stripped)
+      : stripped === schema
+        ? factory(declared)
+        : factory.withRules(nameOf(declared), stripped);
+    return compiled;
+  };
+
+  return {
+    direction,
+    validate: (value: unknown) => resolve().validate(value),
+    defaultPaths: () => {
+      resolve();
+      return paths ?? [];
+    },
+  };
+}
+
+const nameOf = (declared: unknown): string | undefined =>
+  typeof declared === "string"
+    ? declared
+    : ((declared as Record<string, unknown> | null)?.name as string | undefined);
+
+const describeDeclaration = (declared: unknown): string =>
+  typeof declared === "string" ? `'${declared}'` : JSON.stringify(declared);
+
+/**
+ * A copy of `value` deep along exactly the paths a default can be written to and
+ * shared everywhere else.
+ *
+ * A flat shallow copy would not do: AJV's `useDefaults` writes at every level it
+ * finds a default, so a nested default would mutate the structure the caller
+ * still holds. Bounded by the schema's defaults rather than by the size of the
+ * payload — a contract declaring no defaults copies one level and nothing more.
+ */
+export function copyForDefaults(value: unknown, paths: readonly string[][]): unknown {
+  if (!value || typeof value !== "object") return value;
+  let out = shallowCopy(value);
+  for (const path of paths) {
+    // The leaf is what gets written; every CONTAINER above it is what must not
+    // be shared. An `[]` segment fans out: the default lands in each element, so
+    // the array and every element on the path have to be copied too — bailing
+    // there would leave `rows[0]` shared and let a fill mutate the caller's data.
+    out = copyAlong(out, path.slice(0, -1));
+  }
+  return out;
+}
+
+const shallowCopy = (value: object): any =>
+  Array.isArray(value) ? [...value] : { ...(value as Record<string, unknown>) };
+
+function copyAlong(node: unknown, segments: readonly string[]): unknown {
+  if (!node || typeof node !== "object") return node;
+  if (segments.length === 0) return node;
+  const [head, ...rest] = segments;
+
+  if (head === "[]") {
+    if (!Array.isArray(node)) return node;
+    return node.map((item) =>
+      item && typeof item === "object" ? copyAlong(shallowCopy(item), rest) : item,
+    );
+  }
+
+  const container = node as Record<string, unknown>;
+  const child = container[head!];
+  if (!child || typeof child !== "object") return node;
+  container[head!] = copyAlong(shallowCopy(child), rest);
+  return node;
+}
+
+/**
+ * Raise a contract violation as a structured {@link InvokeError}.
+ *
+ * Structured rather than a plain error because the run engine assigns
+ * `INTERNAL_ERROR` to anything that is not an `InvokeError` — a contract
+ * violation would then reach a `catch` block indistinguishable from a crash, and
+ * an author could neither match it nor rethrow it faithfully. These are ambient
+ * kernel codes: catchable by name, and never counted against a kind's own
+ * `throws:` union.
+ *
+ * The message names the target, the direction, and the offending detail, because
+ * a caller several steps away otherwise cannot tell which boundary rejected the
+ * value or which side supplied it.
+ */
+export function contractViolation(
+  direction: ContractDirection,
+  describeTarget: () => string,
+  cause: unknown,
+): Error {
+  // A type's CEL `rules:` raise the author's OWN code — that is the whole point
+  // of declaring one, and `modules/type` documents rule codes as catchable.
+  // Only a structural schema failure is the ambient contract violation.
+  //
+  // Re-raised as a STRUCTURED error carrying that code: the rule itself throws a
+  // `RuntimeError`, which has a code but not the marker a catch block matches
+  // on, so it used to reach `catch` as the generic plain-failure code — the
+  // documented behaviour never actually worked. Wrapping preserves the code and
+  // makes it match.
+  const ruleCode = ruleViolationCode(cause);
+  if (ruleCode) {
+    return new InvokeError(ruleCode, (cause as Error).message, undefined, { cause });
+  }
+
+  const side = direction === "inputType" ? "inputs" : "result";
+  const detail = cause instanceof Error ? cause.message : String(cause);
+  return new InvokeError(
+    CONTRACT_ERROR[direction],
+    `${describeTarget()}: ${side} do not satisfy the declared ${direction}: ${detail}`,
+    undefined,
+    { cause },
+  );
+}
+
+/** Codes the validator itself raises for a STRUCTURAL failure. Anything else
+ *  carrying a code came from a declared rule and belongs to its author. */
+const STRUCTURAL_VALIDATION_CODES = new Set([
+  "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED",
+  "ERR_TYPE_NOT_FOUND",
+]);
+
+function ruleViolationCode(cause: unknown): string | undefined {
+  const code = (cause as { code?: unknown } | null)?.code;
+  if (typeof code !== "string" || code.length === 0) return undefined;
+  return STRUCTURAL_VALIDATION_CODES.has(code) ? undefined : code;
+}
+
+export interface ContractBinding {
+  input?: BoundContract;
+  output?: BoundContract;
+  /** Names the resource in a violation message — the target, so a caller several
+   *  steps away can tell which boundary rejected the value. */
+  describeTarget(): string;
+}
+
+/**
+ * Bind `invoke()` and `provide()` in place.
+ *
+ * `provide()` takes no caller arguments, so it has no input side, but it returns
+ * a value against a declared `outputType` and that result is validated exactly as
+ * an invocable's is — same path, same stream skip, same ambient error code.
+ * `run()` is bound to nothing: parameterless and void, there is nothing to fill
+ * defaults into and no result to validate, so it is guarded statically instead.
+ */
+export function bindContract(instance: ResourceInstance, binding: ContractBinding): void {
+  const { input, output, describeTarget } = binding;
+  if (!input && !output) return;
+
+  if (typeof instance.invoke === "function") {
+    const original = instance.invoke.bind(instance) as (
+      inputs: any,
+      ...rest: unknown[]
+    ) => Promise<unknown>;
+    // EVERY argument is forwarded, not just `inputs`. `invoke(inputs, ctx)`
+    // carries the InvokeContext — cancellation, tracing — as its second
+    // parameter, and a wrapper that takes only `inputs` silently drops it: a
+    // detached body would then never see its cancellation token and a lease
+    // holding across it would never be released. The contract only concerns the
+    // first argument; the rest belong to the caller and the callee.
+    instance.invoke = async (inputs: any, ...rest: unknown[]) => {
+      let effective = inputs;
+      if (input) {
+        effective = copyForDefaults(inputs, input.defaultPaths());
+        // Validate a BIGINT-NORMALIZED view, not the values themselves. CEL
+        // evaluates an integer literal to a BigInt, which a JSON Schema
+        // validator does not recognise as `integer` — so every computed integer
+        // reaching a declared integer input would be rejected for a reason the
+        // author cannot act on. The dispatched values keep their BigInts, since
+        // a controller may need the full 64-bit range.
+        const view = withBigIntsAsNumbers(effective);
+        try {
+          input.validate(view);
+        } catch (error) {
+          throw contractViolation("inputType", describeTarget, error);
+        }
+        // Defaults are additive, so anything the validator filled into the view
+        // is a key the caller omitted — copy exactly those back.
+        effective = mergeFilledDefaults(effective, view);
+      }
+      const result = await original(effective, ...rest);
+      if (output) {
+        try {
+          output.validate(withBigIntsAsNumbers(result));
+        } catch (error) {
+          throw contractViolation("outputType", describeTarget, error);
+        }
+      }
+      return result;
+    };
+  }
+
+  if (output && typeof instance.provide === "function") {
+    const original = instance.provide.bind(instance) as (...args: unknown[]) => Promise<unknown>;
+    instance.provide = async (...args: unknown[]) => {
+      const result = await original(...args);
+      try {
+        output.validate(withBigIntsAsNumbers(result));
+      } catch (error) {
+        throw contractViolation("outputType", describeTarget, error);
+      }
+      return result;
+    };
+  }
+}
+
+/** A structural copy with every BigInt rendered as a Number, for validation
+ *  only. A value beyond the safe-integer range loses precision in the VIEW,
+ *  which can only affect a bound check at the extremes; the dispatched value is
+ *  untouched. Non-plain objects (a live `Stream`, a resource instance) pass
+ *  through by reference — they are not data to be walked. */
+export function withBigIntsAsNumbers(value: unknown): unknown {
+  if (typeof value === "bigint") return Number(value);
+  if (Array.isArray(value)) {
+    let changed = false;
+    const items = value.map((item) => {
+      const next = withBigIntsAsNumbers(item);
+      if (next !== item) changed = true;
+      return next;
+    });
+    return changed ? items : value;
+  }
+  if (!value || typeof value !== "object") return value;
+  if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+  let changed = false;
+  const out: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    const next = withBigIntsAsNumbers(item);
+    if (next !== item) changed = true;
+    out[key] = next;
+  }
+  return changed ? out : value;
+}
+
+/** Copy keys the validator's default-fill added to `view` back onto `target`.
+ *  Only ADDITIONS are taken: a key already present came from the caller and its
+ *  original (possibly BigInt) value is the one to dispatch. */
+function mergeFilledDefaults(target: unknown, view: unknown): unknown {
+  if (target === view) return target;
+  if (!target || typeof target !== "object" || Array.isArray(target)) return target;
+  if (!view || typeof view !== "object" || Array.isArray(view)) return target;
+  const out = target as Record<string, unknown>;
+  for (const [key, filled] of Object.entries(view as Record<string, unknown>)) {
+    if (!(key in out)) out[key] = filled;
+    else out[key] = mergeFilledDefaults(out[key], filled);
+  }
+  return out;
+}

package/src/kernel.ts

@@ -6,9 +6,15 @@ import {
   isModuleKind,
   Loader,
   StaticAnalyzer,
+  type DefResolver,
   type LoadedGraph,
   type ManifestSource,
 } from "@telorun/analyzer";
+import {
+  bindContract,
+  type ContractValidatorFactory,
+  resolveBoundContract,
+} from "./invocation-contract-binding.js";
 import {
   ControllerContext,
   ControllerPolicy,
@@ -348,6 +354,13 @@ export class Kernel implements IKernel {
       "Telo.FileSink",
       await import("./controllers/logging/file-sink-controller.js"),
     );
+    // Data shapes are a kernel concern for the same reason: every kind with an
+    // invocation contract declares one, so `inputType:` must be writable without
+    // first importing a module.
+    this.controllers.registerController(
+      "Telo.JsonSchema",
+      await import("./controllers/type/json-schema-controller.js"),
+    );
   }
 
   /**
@@ -405,8 +418,8 @@ export class Kernel implements IKernel {
     await this.loadBuiltinDefinitions();
 
     // Phase 5: attach injection hook — fires between create() and init() for every resource
-    this.rootContext.preInitHook = (resource, getInstance, isPending) =>
-      this._injectDependencies(resource, getInstance, isPending);
+    this.rootContext.preInitHook = (resource, getInstance, isPending, owner) =>
+      this._injectDependencies(resource, getInstance, isPending, owner);
 
     // Expose definition lookup so invoke()/invokeResolved() can check thrown
     // InvokeError.code against the declared throw union (rule 9). Propagates
@@ -1264,6 +1277,19 @@ export class Kernel implements IKernel {
     const instance = await controller.create(processedResource, ctx);
     if (!instance) return null;
 
+    // Bind the resolved invocation contract to the instance, here at the kernel's
+    // single instance-production site — so every consumer holds an already
+    // enforcing instance, including the majority that read a Phase-5-injected ref
+    // straight off their own config and never reach a dispatch chokepoint.
+    //
+    // For a `base:` child this composes without a special case: the parent's
+    // instance was produced by a nested `_createInstance` (so it is already bound
+    // to the parent's contract), the inherited controller bound the `inputs:` /
+    // `result:` mapping onto it, and this call binds the child's own contract
+    // outermost. One dispatch then checks, in order: child inputs → mapping →
+    // parent inputs → controller → parent result → mapping → child result.
+    this.bindInvocationContract(instance, processedResource, resolvedKind, ctx);
+
     // Fold the resource's fire-and-forget drain into its own teardown: tearing
     // the resource down drains the background tasks it spawned (the kernel just
     // calls teardown() — it tracks no tasks itself). A drain with no pending
@@ -1282,14 +1308,58 @@ export class Kernel implements IKernel {
     // init() on the wrapper would be invisible to the original invoke(), which still
     // runs with `this === instance`. Mutating in place also preserves the prototype
     // chain — class-declared methods remain reachable.
+    // Every argument is forwarded: `invoke(inputs, ctx)` carries the
+    // InvokeContext (cancellation, tracing) as its second parameter, and a
+    // wrapper that declares only `inputs` silently drops it.
     const originalInvoke = instance.invoke!.bind(instance);
-    instance.invoke = async (inputs: any) => {
+    instance.invoke = async (inputs: any, ...rest: unknown[]) => {
       const expanded = evalContext.expandPaths(inputs as Record<string, unknown>, runtime);
-      return originalInvoke(expanded);
+      return (originalInvoke as (i: any, ...r: unknown[]) => Promise<unknown>)(expanded, ...rest);
     };
     return { instance, ctx, resource: processedResource };
   }
 
+  /**
+   * Resolve and bind both directions of a resource's invocation contract.
+   *
+   * The declaration is layered instance-manifest → nearest along `extends`;
+   * contracts never merge (a call signature is not additive the way construction
+   * config is), so a definition that declares one fully replaces its ancestor's.
+   * Resolution runs in the scope that DECLARED each definition — an `extends`
+   * alias is lexical, and a `telo#Type` reference goes through import aliases, so
+   * a chain crossing module boundaries re-scopes at every hop.
+   */
+  private bindInvocationContract(
+    instance: ResourceInstance,
+    resource: ResourceManifest,
+    resolvedKind: string,
+    ctx: ResourceContext,
+  ): void {
+    const definition = this.controllers.getDefinition(resolvedKind);
+    if (!definition) return;
+
+    const impl = ctx as ResourceContextImpl;
+    const factory = Object.assign((typeRef: unknown) => impl.createTypeValidator(typeRef as any), {
+      schemaOf: (typeRef: unknown) => impl.resolveTypeSchema(typeRef),
+      resolveRef: (ref: string) => impl.lookupSchema(ref) as Record<string, any> | undefined,
+      withRules: (name: string | undefined, schema: Record<string, any>) =>
+        impl.createTypeValidatorWithRules(name, schema),
+    }) as ContractValidatorFactory;
+
+    const resolveDef: DefResolver = (kind, from) =>
+      this.registry.resolveDefinitionIn(kind, from?.metadata?.module);
+
+    const input = resolveBoundContract("inputType", resource, definition, resolveDef, factory);
+    const output = resolveBoundContract("outputType", resource, definition, resolveDef, factory);
+    if (!input && !output) return;
+
+    bindContract(instance, {
+      input,
+      output,
+      describeTarget: () => `${resolvedKind}/${resource.metadata?.name ?? "<unnamed>"}`,
+    });
+  }
+
   /**
    * Create phase for an inherited (concrete-`extends`) definition's parent: runs
    * the ordinary create pipeline (controller resolution + lazy load, schema
@@ -1314,11 +1384,18 @@ export class Kernel implements IKernel {
    * field map and replaces each {kind, name} reference value (outside scope visibility
    * paths) with the live ResourceInstance returned by getInstance(name). Fields within
    * scope paths are left as {kind, name} — the controller resolves them at runtime.
+   *
+   * `owner` is the context the resource belongs to, and the scope handle built for an
+   * `x-telo-scope` field hangs off it rather than off the root: a `with:` block's inline
+   * declarations name their kinds through the import aliases of the module that DECLARED
+   * the resource, so a library's scoped `kind: OAuth.RedirectListener` resolves against
+   * that library's imports — the root has never heard of the alias.
    */
   private _injectDependencies(
     resource: ResourceManifest,
     getInstance: (name: string, alias?: string) => ResourceInstance | undefined,
-    isPending?: (name: string) => boolean,
+    isPending: ((name: string) => boolean) | undefined,
+    owner: IEvaluationContext,
   ): void {
     this.registry.iterateFieldEntries(
       resource,
@@ -1349,7 +1426,7 @@ export class Kernel implements IKernel {
               );
             }
           }
-          (resource as Record<string, unknown>)[fieldPath] = this.rootContext.createScopeHandle(
+          (resource as Record<string, unknown>)[fieldPath] = owner.createScopeHandle(
             val as ResourceManifest[],
           );
         }

package/src/module-context.ts

@@ -404,6 +404,33 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   getInstance(name: string): unknown {
     const entry = this.resourceInstances.get(name);
     if (!entry) {
+      // A name this module DID declare but that has no instance is never an
+      // unknown name — reporting it as "not found ... available resources:
+      // <imports>" reads as a typo in a name declared right there. Which of the
+      // two real situations it is depends on whether this context is still
+      // initializing:
+      //
+      //  - mid-init: a dependency-ordering deferral. Defer exactly as Phase-5
+      //    injection does, so the multi-pass loop retries and the failure is
+      //    attributed to the dependency.
+      //  - after init: no later pass is coming (a resource registered into the
+      //    module after the loop drained its queue stays pending forever), so
+      //    promising one would send the developer after a retry that will never
+      //    happen. Say what is actually true.
+      if (this.hasManifest(name)) {
+        if (this.state !== "Initialized") {
+          throw new RuntimeError(
+            "ERR_LOCAL_REF_PENDING",
+            `Local reference '${name}' is registered but not initialized yet (deferring to a later init pass)`,
+          );
+        }
+        throw new RuntimeError(
+          "ERR_RESOURCE_NOT_FOUND",
+          `Resource '${name}' is declared in this module but was never initialized, so it cannot be dispatched. ` +
+            `A resource registered after the module's init loop finished is never created — declare it at module scope, ` +
+            `or inside the '${name}'-owning scope's own resource list.`,
+        );
+      }
       throw new Error(
         `Resource '${name}' not found in module context. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
       );

package/src/resource-context.ts

@@ -174,6 +174,87 @@ export class ResourceContextImpl implements ResourceContext {
     return this.validator.getTypeRules(name);
   }
 
+  /** The JSON Schema behind a type field, resolved the same four ways
+   *  {@link createTypeValidator} resolves it (named ref, `{kind, name}` ref
+   *  object, inline `{kind, schema}`, raw schema), and then followed through a
+   *  bare `telo://<module>/<Type>` `$ref` to the schema that type registered.
+   *
+   *  Following the `$ref` matters because AJV resolves cross-schema references
+   *  against its own registry at compile time, while the kernel's registry is
+   *  what actually holds these — a `Type.JsonSchema` registers under the
+   *  canonical URI as a *key*, which AJV does not treat as a resolvable id. A
+   *  definition whose whole contract is `{ $ref: "telo://Self/TokenSet" }` (the
+   *  sanctioned way to declare a shape once and reference it from several kinds)
+   *  would otherwise be uncompilable at dispatch. Resolving here means AJV is
+   *  handed the real schema and never has to resolve the reference at all.
+   *
+   *  Contract binding needs the schema rather than just a compiled validator
+   *  anyway, for the decisions a validator cannot answer: which properties carry
+   *  `x-telo-stream` and must be exempt from the walk, and which paths a
+   *  `default:` can be written to. Returns undefined when the reference resolves
+   *  to nothing. */
+  resolveTypeSchema(typeRef: unknown): Record<string, any> | undefined {
+    return this.followTypeAlias(this.readTypeSchema(typeRef), new Set());
+  }
+
+  private readTypeSchema(typeRef: unknown): Record<string, any> | undefined {
+    if (!typeRef) return undefined;
+    if (typeof typeRef === "string") return this.validator.getSchema(typeRef) as any;
+    if (typeof typeRef !== "object") return undefined;
+    const ref = typeRef as Record<string, any>;
+    if (ref.schema && typeof ref.schema === "object") return ref.schema;
+    if (typeof ref.name === "string") return this.validator.getSchema(ref.name) as any;
+    if (ref.type || ref.properties || ref.$ref) return ref;
+    return undefined;
+  }
+
+  /**
+   * Follow a schema that is nothing but a `$ref` to a registered type, so the
+   * schema-level questions (which properties are streams, which paths carry a
+   * default) are asked of the real shape rather than of an alias.
+   *
+   * Only the whole-document alias form is followed, and only to READ it — the
+   * schema handed to AJV keeps its `$ref`s intact, because AJV resolves them
+   * itself against the registered ids and each type stays its own document with
+   * its own `$defs`. Inlining instead would move a `$ref: "#/$defs/X"` out of the
+   * document that defines `$defs.X`.
+   *
+   * `seen` guards a cycle two mutually-referencing types would otherwise spin on.
+   * A `$ref` alongside other keywords is left alone: that is a composition, not
+   * an alias.
+   */
+  private followTypeAlias(
+    schema: Record<string, any> | undefined,
+    seen: Set<string>,
+  ): Record<string, any> | undefined {
+    let current = schema;
+    while (
+      current &&
+      typeof current.$ref === "string" &&
+      Object.keys(current).length === 1 &&
+      !seen.has(current.$ref)
+    ) {
+      seen.add(current.$ref);
+      const target = this.validator.getSchema(current.$ref) as Record<string, any> | undefined;
+      if (!target) return current;
+      current = target;
+    }
+    return current;
+  }
+
+  /** Compile `schema` but compose the CEL `rules:` registered under `name`.
+   *
+   *  A named type's rules are its business invariants, and they are reachable
+   *  only through the name. {@link createTypeValidator} composes them when it is
+   *  handed a bare name, but a caller that must adjust the schema first — the
+   *  contract binding, which strips `x-telo-stream` properties before validating
+   *  — would otherwise have to choose between the adjustment and the rules. */
+  createTypeValidatorWithRules(name: string | undefined, schema: Record<string, any>) {
+    const base = this.validator.compile(schema);
+    const rules = name ? this.validator.getTypeRules(name) : undefined;
+    return rules && rules.length > 0 ? this.validator.composeWithRules(base, name!, rules) : base;
+  }
+
   createTypeValidator(typeRef: string | Record<string, any> | undefined) {
     if (!typeRef) return new NoopValidator();