@telorun/kernel 0.67.0 → 0.68.0

package/src/application-env.ts

@@ -1,7 +1,19 @@
-import { type DefResolver, effectiveAuthorSchema, residualEntrySchema } from "@telorun/analyzer";
-import type { ResourceDefinition } from "@telorun/sdk";
+import {
+  type DefResolver,
+  effectiveAuthorSchema,
+  residualEntrySchema,
+  withStreamPropertiesSkipped,
+} from "@telorun/analyzer";
+import type {
+  ResourceContext,
+  ResourceDefinition,
+  ResourceManifest,
+  TypeRule,
+} from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
+import { create as createJsonSchemaType } from "./controllers/type/json-schema-controller.js";
 import { SchemaValidator } from "./schema-validator.js";
+import { resolveTypeFieldSchema } from "./type-field-schema.js";
 
 type EntryType = "string" | "integer" | "number" | "boolean" | "object" | "array";
 
@@ -144,6 +156,63 @@ export function precompileApplicationEnvSchemas(
   }
 }
 
+/**
+ * Register every `Telo.JsonSchema` resource's resolved schema into `validator`,
+ * ahead of the contract warm below.
+ *
+ * A contract declared as `{kind: Telo.JsonSchema, schema: {$ref: "telo:m/X"}}`
+ * — what `oauth-client` and `vector-store` write — is compiled at runtime from
+ * the schema registered under that id, reached by following the alias. With no
+ * types registered the warm follows it to the `$ref` wrapper itself, AJV refuses
+ * the unresolvable reference, and the entry is silently not baked while the
+ * runtime goes on compiling something else: a guaranteed miss for exactly the
+ * modules that declare their shapes once and reference them.
+ *
+ * Runs the REAL type controller rather than re-deriving registration here. The
+ * three names a type registers under, the canonical `telo:` id and the `extends`
+ * merge are its rules; a second implementation would drift into baking schemas
+ * under keys the runtime never asks for — the failure this whole pass exists to
+ * remove. The loop mirrors the kernel's multi-pass init (`create` returns null
+ * while a parent type is unregistered) and stops as soon as a pass registers
+ * nothing new, so an unresolvable parent ends it instead of spinning.
+ *
+ * The deprecated `Type.JsonSchema` is not warmed: it is a module kind with its
+ * own controller, and reaching for this one would be assuming the two stayed
+ * identical.
+ */
+export async function precompileTypeSchemas(
+  manifests: Array<Record<string, any>>,
+  validator: SchemaValidator,
+): Promise<void> {
+  const ctx = {
+    lookupSchema: (name: string) => validator.getSchema(name),
+    registerSchema: (name: string, schema: object) => validator.addSchema(name, schema),
+    registerTypeRules: (name: string, rules: TypeRule[]) => validator.addTypeRules(name, rules),
+  } as unknown as ResourceContext;
+
+  let pending = manifests.filter(
+    (m) =>
+      m?.kind === "Telo.JsonSchema" &&
+      m.schema &&
+      typeof m.metadata?.name === "string" &&
+      typeof m.metadata?.module === "string",
+  );
+  while (pending.length > 0) {
+    const deferred: Array<Record<string, any>> = [];
+    for (const m of pending) {
+      try {
+        if ((await createJsonSchemaType(m as unknown as ResourceManifest, ctx)) === null) {
+          deferred.push(m);
+        }
+      } catch {
+        // A broken type surfaces through analysis / runtime, not the warm pass.
+      }
+    }
+    if (deferred.length === pending.length) break;
+    pending = deferred;
+  }
+}
+
 /**
  * Build-time cache warm for resource-config validators. The runtime
  * `_createInstance` compiles the declaring `Telo.Definition`'s `schema` to
@@ -188,11 +257,31 @@ export function precompileDefinitionSchemas(
       // Broken schemas are reported by analysis / runtime, not the warm pass.
     }
   };
+  const lookup = (name: string) => validator.getSchema(name);
+  // A contract validator is compiled from the RESOLVED schema with its
+  // `x-telo-stream` properties stripped, never from the declaration — see
+  // `resolveBoundContract`. Baking the declaration instead bakes a validator for
+  // `{kind, schema}`, which no dispatch asks for. A declaration that needs the
+  // runtime type registry (a bare name, a `{kind, name}` ref) resolves to
+  // nothing here — named types register when their resources initialize, long
+  // after the warm — so it is skipped rather than baked wrong.
+  const compileContract = (declared: unknown): void => {
+    if (declared === undefined || declared === null) return;
+    try {
+      const schema = resolveTypeFieldSchema(declared, lookup);
+      if (!schema) return;
+      compile(withStreamPropertiesSkipped(schema, (ref) => lookup(ref) as any));
+    } catch {
+      // An unresolvable contract is a dispatch-time error, not a warm failure.
+    }
+  };
   for (const m of manifests) {
+    // A per-instance contract overrides the kind's, so a resource declaring its
+    // own narrowing is what the runtime compiles for that instance.
+    compileContract(m?.inputType);
+    compileContract(m?.outputType);
     if (m?.kind !== "Telo.Definition") continue;
     compile(m.schema);
-    compile(m.inputType);
-    compile(m.outputType);
     if (resolverFor && m.extends) {
       // Mirrors the runtime stamp in `resource-definition-controller`; sharing
       // `effectiveAuthorSchema` is what keeps the two keys identical.

package/src/kernel.ts

@@ -72,6 +72,7 @@ import {
   collectDeclaredEnvKeys,
   precompileApplicationEnvSchemas,
   precompileDefinitionSchemas,
+  precompileTypeSchemas,
   resolveApplicationEnv,
 } from "./application-env.js";
 import { policyFingerprint } from "./runtime-registry.js";
@@ -571,6 +572,26 @@ export class Kernel implements IKernel {
       // same content-addressed `__validators/` cache the runtime reads. The
       // resolver lets it also bake each `extends` child's inheritance-resolved
       // schema — the form the runtime actually validates against.
+      //
+      // Named types first: a contract that is a `$ref` to one resolves through
+      // the schema registry, which at runtime is populated by the type
+      // resources' own init. Without them a `$ref` contract bakes nothing.
+      //
+      // Fed from the GRAPH, not from `staticManifests`: flatten forwards every
+      // module's definitions but only the ENTRY's resource instances, and a
+      // named type is a resource instance — so a library that declares its
+      // shapes once and `$ref`s them (`oauth-client`, `vector-store`) has no
+      // type doc in the flattened view at all.
+      const graphDocs = [...analysisGraph.modules.values()].flatMap((mod) =>
+        flattenLoadedModule(mod),
+      );
+      // Canonicalize `telo://Self/<type>` to the id the type registers under.
+      // `analyze()` did this to its own view; these projections are separate
+      // objects, and an un-canonicalized `$ref` resolves to nothing here while
+      // the runtime resolves it fine — a guaranteed miss on exactly the
+      // contracts that reference a named shape.
+      this.registry.resolveSchemaTypeRefs([...graphDocs, ...staticManifests]);
+      await precompileTypeSchemas(graphDocs, this.sharedSchemaValidator);
       precompileDefinitionSchemas(staticManifests, this.sharedSchemaValidator, (def) =>
         this.registry.resolverForDefinition(def),
       );

package/src/resource-context.ts

@@ -43,6 +43,7 @@ interface KernelModuleContext {
   getLoggingConfig?(): ScopeConfig | undefined;
 }
 import { stripCompiledValues } from "./schema-compiled-values.js";
+import { resolveTypeFieldSchema } from "./type-field-schema.js";
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
 import { Kernel } from "./kernel.js";
@@ -179,7 +180,12 @@ export class ResourceContextImpl implements ResourceContext {
     if (!schema) {
       return new NoopValidator();
     }
-    return this.validator.compile(schema);
+    // Never persisted: the schema is author data in a RESOURCE field, which the
+    // build-time warm does not walk, so a disk entry could only ever miss and
+    // be rewritten on every boot. Compiling through the kernel's validator is
+    // still what keeps one engine in the process — its formats, its `x-telo-*`
+    // keywords, its non-strict mode.
+    return this.validator.compile(schema, { persist: false });
   }
 
   registerSchema(name: string, schema: object): void {
@@ -216,54 +222,13 @@ export class ResourceContextImpl implements ResourceContext {
    *  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`.
+   *  to nothing.
    *
-   * `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;
+   *  Shared with the build-time validator warm through
+   *  {@link resolveTypeFieldSchema} — the warm must land on the same schema
+   *  object the runtime compiles, or its baked entry is one nothing asks for. */
+  resolveTypeSchema(typeRef: unknown): Record<string, any> | undefined {
+    return resolveTypeFieldSchema(typeRef, (name) => this.validator.getSchema(name));
   }
 
   /** Compile `schema` but compose the CEL `rules:` registered under `name`.

package/src/schema-compiled-values.ts

@@ -61,6 +61,35 @@ function collectSchemaProperties(
   return props;
 }
 
+/** True when a ref slot is holding CONFIG rather than a reference.
+ *
+ *  A slot annotated `x-telo-ref` is normally handed back whole, but the
+ *  annotation can sit on a node that is a reference AND a config carrier at
+ *  once: `targets:` puts it on the array ITEM so a bare `!ref Foo` is accepted,
+ *  while the same item may be a step object (`{ref, when}` /
+ *  `{invoke, inputs, when}`) whose `when` is a CEL guard that must be stripped
+ *  like any other. Told apart by what the value IS, three ways:
+ *
+ *  - a reference carries a `kind` — `resolveRefSentinels` rewrites a `!ref` to
+ *    `{kind, name, alias?}`, and the only other object a ref slot admits is an
+ *    inline definition (`{kind, …config}`);
+ *  - a live instance is either not a plain object, or exposes a method (a
+ *    controller's `create()` may return an object literal — `Assert.Schema`
+ *    does). Copying one is what the walk exists to avoid, and its graph is
+ *    routinely cyclic;
+ *  - what is left came from YAML, where a function cannot appear. */
+function isConfigAtRefSlot(value: unknown): boolean {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return false;
+  const obj = value as Record<string, unknown>;
+  if ("kind" in obj) return false;
+  for (const member of Object.values(obj)) {
+    if (typeof member === "function") return false;
+  }
+  return true;
+}
+
 /** Replaces CompiledValue wrappers with schema-appropriate placeholders for schema validation.
  *  Template strings were compiled from YAML at load time; this restores a shape
  *  that AJV can validate without evaluating expressions. When no schema is
@@ -88,10 +117,13 @@ export function stripCompiledValues(
     const resolved = resolveSchemaRef(nodeSchema, root);
 
     if (isCompiledValue(value)) return placeholderForSchema(resolved);
-    // A slot the schema declares as a reference is never config: it holds a
-    // `{kind, name}` ref or the live instance Phase 5 replaced it with, and the
-    // schema declares no shape to validate against either way.
-    if (resolved["x-telo-ref"] !== undefined) return value;
+    // A slot the schema declares as a reference is never config when it HOLDS a
+    // reference: a `{kind, name}` ref or the live instance Phase 5 replaced it
+    // with, and the schema declares no shape to validate against either way. A
+    // ref slot carrying config beside the ref keeps walking — bailing there left
+    // a boot target's `when: !cel` a CompiledValue for AJV to reject as
+    // "must be string", which is the whole gated-target form.
+    if (resolved["x-telo-ref"] !== undefined && !isConfigAtRefSlot(value)) return value;
 
     if (Array.isArray(value)) {
       const itemSchema = resolveSchemaRef((resolved.items ?? {}) as Record<string, unknown>, root);

package/src/schema-validator.ts

@@ -146,6 +146,64 @@ function collapseSentinelsToSource(value: unknown): unknown {
   return value;
 }
 
+/** Schema keywords whose VALUE is a map keyed by author-chosen names rather
+ *  than by keyword. A name may legitimately be `x-telo-…`, so the strip below
+ *  must not treat a key in one of these maps as an annotation. */
+const NAME_KEYED_SCHEMA_KEYWORDS = new Set([
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  "dependentRequired",
+  "$defs",
+  "definitions",
+]);
+
+/** Schema keywords whose value is DATA, not a subschema. The strip must not
+ *  descend into them at all: an `x-telo-…` key inside a `const` / `default` /
+ *  `enum` member is part of the value being matched or filled, so removing it
+ *  would change what the validator accepts and what it writes — and would make
+ *  two schemas that differ only there hash alike. */
+const DATA_VALUE_KEYWORDS = new Set(["const", "default", "enum", "examples"]);
+
+/** Deep-clone `schema` without its `x-telo-*` annotations — applied, like
+ *  {@link collapseSentinelsToSource}, before both AJV compilation and cache
+ *  hashing.
+ *
+ *  Every `x-telo-*` keyword is analyzer/editor metadata: AJV runs `strict:
+ *  false` and registers the known ones as no-op keywords, so none of them emits
+ *  a single line of validation code. Leaving them in the hashed form makes the
+ *  cache key sensitive to differences that cannot change what the validator
+ *  does — and one such difference is real and systematic. The analyzer rewrites
+ *  `x-telo-ref.kind` to its canonical `<module>.<Kind>` in the declaring scope
+ *  (`resolveSchemaRefKinds`), and `telo install`'s warm pass bakes THAT view;
+ *  the kernel's controller registry never runs the rewrite, so at runtime the
+ *  same kind's schema still reads `Self.Connection`. Two keys, one validator:
+ *  every kind whose schema declares an alias-qualified ref missed the baked
+ *  cache on every boot and tried to rewrite it — the EACCES noise on a
+ *  read-only image.
+ *
+ *  Stripping is what makes the key describe the compiled validator and nothing
+ *  else, so the two views converge without either side having to agree on an
+ *  annotation's spelling. `normalizeRefSlots` runs FIRST and is unaffected: it
+ *  reads `x-telo-ref` to drop a legacy scalar `type` at a ref slot, which does
+ *  change validation, and it has already done so by the time this runs. */
+function stripTeloAnnotations(value: unknown, nameKeyed = false): unknown {
+  // An array's items are schema nodes (`allOf`, tuple `items`), never names.
+  if (Array.isArray(value)) return value.map((item) => stripTeloAnnotations(item));
+  if (!value || typeof value !== "object") return value;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (!nameKeyed && k.startsWith("x-telo-")) continue;
+    // A data-bearing keyword's value is carried over verbatim; a name-keyed
+    // map's VALUES are schema nodes again, so only its keys are exempt.
+    out[k] =
+      !nameKeyed && DATA_VALUE_KEYWORDS.has(k)
+        ? v
+        : stripTeloAnnotations(v, !nameKeyed && NAME_KEYED_SCHEMA_KEYWORDS.has(k));
+  }
+  return out;
+}
+
 export class SchemaValidator {
   private ajv: InstanceType<typeof Ajv>;
   private typeRules = new Map<string, TypeRule[]>();
@@ -162,6 +220,13 @@ export class SchemaValidator {
    *  process — `compiledValidators` is keyed by object identity and would
    *  miss those cases. */
   private hashCache = new Map<string, DataValidator>();
+  /** Hashes whose compile went through the disk layer. A `persist: false`
+   *  compile populates `hashCache` too — a repeat within the process should
+   *  still collapse — but must not be mistaken for a baked entry: returning it
+   *  to a persisting caller would suppress that caller's write permanently, so
+   *  content shared with a warmable schema would never reach the cache. Such a
+   *  caller falls through and compiles again, this time with the disk layer. */
+  private persistedHashes = new Set<string>();
   /** Where cache-failure diagnostics go. Injected rather than reached for
    *  globally: this class is constructed outside the kernel's stdio scope, and
    *  §13.1 forbids the kernel writing to `process.stderr` directly. Defaults to
@@ -239,7 +304,18 @@ export class SchemaValidator {
     this.cacheWritable = opts?.write ?? true;
   }
 
-  compile(schema: any): DataValidator {
+  /** Compile `schema` to a validator, reusing the in-memory and on-disk caches.
+   *
+   *  `persist: false` keeps the compile in memory only — no disk read, no disk
+   *  write. It is for a schema the build-time warm cannot see: an author-written
+   *  JSON Schema sitting in a RESOURCE field (`ctx.createSchemaValidator`),
+   *  rather than a kind's config schema or an invocation contract. Those are
+   *  baked by `precompileDefinitionSchemas`; a resource-field schema never was,
+   *  so persisting it only ever produced a miss-then-write on every boot — the
+   *  EACCES noise on a read-only image. Declining to own what it cannot warm is
+   *  the cache being honest, not a capability given up: the in-memory layers
+   *  still collapse a repeat compile within the process. */
+  compile(schema: any, options?: { persist?: boolean }): DataValidator {
     if (schema && typeof schema === "object") {
       const cached = this.compiledValidators.get(schema as object);
       if (cached) return cached;
@@ -284,7 +360,7 @@ export class SchemaValidator {
     // precompiled (runtime) views of one schema land on the same cache key. The
     // hashed and the compiled schema are this same canonical form. See
     // `collapseSentinelsToSource`.
-    const sanitized = collapseSentinelsToSource(injected);
+    const sanitized = collapseSentinelsToSource(stripTeloAnnotations(injected));
 
     const hash = createHash("sha256")
       .update(
@@ -295,15 +371,17 @@ export class SchemaValidator {
       )
       .digest("hex")
       .slice(0, 32);
+    const persist = options?.persist ?? true;
     const cachedByHash = this.hashCache.get(hash);
-    if (cachedByHash) {
+    if (cachedByHash && (!persist || this.persistedHashes.has(hash))) {
       if (schema && typeof schema === "object") {
         this.compiledValidators.set(schema as object, cachedByHash);
       }
       return cachedByHash;
     }
 
-    const validate = this.compileAjvOrLoadCached(sanitized, hash);
+    const validate = this.compileAjvOrLoadCached(sanitized, hash, persist);
+    if (persist) this.persistedHashes.add(hash);
 
     const validator = {
       validate: (data: any) => {
@@ -342,8 +420,12 @@ export class SchemaValidator {
   private compileAjvOrLoadCached(
     schema: any,
     hash: string,
+    persist: boolean,
   ): ValidateFunction {
-    const cacheDir = this.cacheDir;
+    // `persist: false` drops the whole disk layer — the read too, not just the
+    // write. Nothing bakes these entries, so a lookup is an ENOENT probe whose
+    // only possible hit is one this process wrote on an earlier run.
+    const cacheDir = persist ? this.cacheDir : undefined;
     if (cacheDir) {
       const cachePath = path.join(cacheDir, `${hash}.cjs`);
       try {

package/src/type-field-schema.ts

@@ -0,0 +1,77 @@
+/**
+ * Resolve a type field (`inputType` / `outputType`, or any `telo#Type` slot) to
+ * the JSON Schema behind it.
+ *
+ * Extracted from `ResourceContextImpl` so the build-time validator warm
+ * (`precompileDefinitionSchemas`) resolves a contract through the SAME code the
+ * runtime binding does. It used to compile the raw declaration instead —
+ * `{kind: Telo.JsonSchema, schema: {...}}`, which is not a JSON Schema at all,
+ * so `SchemaValidator.compile` read it as a property map and baked a validator
+ * for `{kind, schema}` that no dispatch would ever ask for. One resolver, one
+ * cache key.
+ *
+ * `getSchema` is the registry lookup — `SchemaValidator.getSchema` at both call
+ * sites. At warm time named types are not registered yet, so a bare-name
+ * declaration resolves to `undefined` and the caller simply skips it.
+ */
+export type SchemaLookup = (name: string) => object | undefined;
+
+/** The four declaration forms: a registered type's name, a `{kind, name}` ref
+ *  object, an inline `{kind, schema}` type resource, and a raw JSON Schema. */
+function readTypeSchema(
+  typeRef: unknown,
+  getSchema: SchemaLookup,
+): Record<string, any> | undefined {
+  if (!typeRef) return undefined;
+  if (typeof typeRef === "string") return getSchema(typeRef) as Record<string, any> | undefined;
+  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 getSchema(ref.name) as Record<string, any> | undefined;
+  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.
+ */
+function followTypeAlias(
+  schema: Record<string, any> | undefined,
+  getSchema: SchemaLookup,
+): Record<string, any> | undefined {
+  const seen = new Set<string>();
+  let current = schema;
+  while (
+    current &&
+    typeof current.$ref === "string" &&
+    Object.keys(current).length === 1 &&
+    !seen.has(current.$ref)
+  ) {
+    seen.add(current.$ref);
+    const target = getSchema(current.$ref) as Record<string, any> | undefined;
+    if (!target) return current;
+    current = target;
+  }
+  return current;
+}
+
+/** The JSON Schema a type field names, or `undefined` when it resolves to
+ *  nothing (an unregistered name, a declaration in none of the four forms). */
+export function resolveTypeFieldSchema(
+  typeRef: unknown,
+  getSchema: SchemaLookup,
+): Record<string, any> | undefined {
+  return followTypeAlias(readTypeSchema(typeRef, getSchema), getSchema);
+}