@telorun/kernel 0.60.0 → 0.62.0

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();
 

package/src/schema-compiled-values.ts

@@ -65,27 +65,67 @@ function collectSchemaProperties(
  *  Template strings were compiled from YAML at load time; this restores a shape
  *  that AJV can validate without evaluating expressions. When no schema is
  *  supplied every compiled value collapses to `""` (the `default` branch of
- *  `placeholderForSchema`), matching the schema-unaware strip. */
+ *  `placeholderForSchema`), matching the schema-unaware strip.
+ *
+ *  The walk stops short of anything that is not plain config, mirroring
+ *  `buildResolvedProperties`: by the time a resource reaches validation its ref
+ *  slots may already hold LIVE resource instances (a template passing the
+ *  caller's client down with `client: !cel "self.client"` hands the child the
+ *  injected instance, not a ref), and a controller's object graph is
+ *  arbitrarily deep and routinely cyclic — walking one overflows the stack
+ *  instead of producing a diagnostic, and there is nothing inside it to strip. */
 export function stripCompiledValues(
   v: unknown,
   schema: Record<string, unknown> = {},
   rootSchema?: Record<string, unknown>,
 ): unknown {
   const root = rootSchema ?? schema;
-  const resolved = resolveSchemaRef(schema, root);
+  // Ancestors on the current path, so a genuine cycle stops while a sub-object
+  // that merely appears twice is still stripped both times.
+  const ancestors = new Set<object>();
 
-  if (isCompiledValue(v)) return placeholderForSchema(resolved);
-  if (Array.isArray(v)) {
-    const itemSchema = resolveSchemaRef((resolved.items ?? {}) as Record<string, unknown>, root);
-    return v.map((item) => stripCompiledValues(item, itemSchema, root));
-  }
-  if (v !== null && typeof v === "object") {
-    const props = collectSchemaProperties(resolved);
-    const out: Record<string, unknown> = {};
-    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
-      out[k] = stripCompiledValues(val, props[k] ?? {}, root);
+  const walk = (value: unknown, nodeSchema: Record<string, unknown>): unknown => {
+    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;
+
+    if (Array.isArray(value)) {
+      const itemSchema = resolveSchemaRef((resolved.items ?? {}) as Record<string, unknown>, root);
+      return walkGuarded(value, () => value.map((item) => walk(item, itemSchema)));
     }
-    return out;
-  }
-  return v;
+    if (value !== null && typeof value === "object") {
+      // A class instance (a client, a pool, a stream) carries no CompiledValues
+      // and is not described by the schema — copying it is pure risk.
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) return value;
+
+      const props = collectSchemaProperties(resolved);
+      return walkGuarded(value, () => {
+        const out: Record<string, unknown> = {};
+        for (const [k, val] of Object.entries(value as Record<string, unknown>)) {
+          out[k] = walk(val, props[k] ?? {});
+        }
+        return out;
+      });
+    }
+    return value;
+  };
+
+  /** Runs `fn` with `node` marked as an ancestor; a node already on the path is
+   *  a cycle and is returned as-is rather than recursed into. */
+  const walkGuarded = (node: object, fn: () => unknown): unknown => {
+    if (ancestors.has(node)) return node;
+    ancestors.add(node);
+    try {
+      return fn();
+    } finally {
+      ancestors.delete(node);
+    }
+  };
+
+  return walk(v, schema);
 }

package/src/schema-validator.ts

@@ -8,6 +8,20 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { formatAjvErrors } from "./manifest-schemas.js";
+
+/** Render a value for an error message without ever throwing.
+ *
+ *  `JSON.stringify` refuses BigInt, and CEL evaluates an integer literal to one —
+ *  so serializing the offending data threw from inside the message template and
+ *  the thrown stringify error REPLACED the validation failure. The author was
+ *  told "cannot serialize BigInt" instead of which field was wrong. */
+function describeValue(data: unknown): string {
+  try {
+    return JSON.stringify(data, (_k, v) => (typeof v === "bigint" ? `${v}` : v)) ?? String(data);
+  } catch {
+    return String(data);
+  }
+}
 import {
   EXACT_TEMPLATE_REGEX,
   isTaggedSentinel,
@@ -297,7 +311,7 @@ export class SchemaValidator {
         if (!isValid) {
           throw new RuntimeError(
             "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED",
-            `Invalid value passed: ${JSON.stringify(data)}. Error: ${formatAjvErrors(validate.errors)}`,
+            `Invalid value passed: ${describeValue(data)}. Error: ${formatAjvErrors(validate.errors)}`,
           );
         }
       },

package/src/static-analysis-diagnostics.ts

@@ -0,0 +1,51 @@
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "@telorun/analyzer";
+import type { DiagnosticOrigin, RuntimeDiagnostic } from "@telorun/sdk";
+
+/**
+ * Carry a static-analysis diagnostic into the runtime failure set.
+ *
+ * The analyzer's `data` — the file, the field path within it, and the owning
+ * resource — travels as `origin`, alongside the diagnostic's own `range` for
+ * the failures that have no field path to look up (a YAML parse error knows
+ * where the syntax broke but has no parsed tree to index). That is what lets a
+ * renderer resolve the same `file:line:col` `telo check` prints; flattening it
+ * into `message` leaves `telo run` pointing at nothing, which is the whole
+ * reason the two commands used to disagree about one error.
+ *
+ * The sibling of `init-failure-diagnostics.ts`: both turn a kernel failure set
+ * into `RuntimeDiagnostic[]`, one for what static analysis rejected and one for
+ * what failed to initialize.
+ */
+export function staticDiagnosticToRuntime(d: AnalysisDiagnostic): RuntimeDiagnostic {
+  const data = d.data as DiagnosticOrigin | undefined;
+  const origin: DiagnosticOrigin = {};
+  if (data?.filePath !== undefined) origin.filePath = data.filePath;
+  if (data?.path !== undefined) origin.path = data.path;
+  if (data?.resource !== undefined) origin.resource = data.resource;
+  if (d.range !== undefined) origin.range = d.range;
+  return {
+    // Mapped, not assumed: every current caller passes a pre-filtered error set,
+    // but a warning routed through here must not be rendered in red and counted
+    // toward the exit code. `AnalysisDiagnostic.severity` is optional and its
+    // scale runs Error(1) → Hint(4), so anything looser than Error is a warning.
+    severity: (d.severity ?? DiagnosticSeverity.Warning) <= DiagnosticSeverity.Error
+      ? "error"
+      : "warning",
+    message: d.message,
+    code: d.code !== undefined ? String(d.code) : undefined,
+    resource: describeResource(data?.resource),
+    // Only when something is actually set, so `origin` stays usable as the
+    // "this came from static analysis" predicate its contract promises.
+    ...(Object.keys(origin).length > 0 ? { origin } : {}),
+  };
+}
+
+/** `Kind.name`, or whichever half is present — a diagnostic carrying only one
+ *  of them used to render as `undefined.foo`. */
+function describeResource(
+  resource: { kind?: string; name?: string } | undefined,
+): string | undefined {
+  if (!resource) return undefined;
+  const parts = [resource.kind, resource.name].filter((p): p is string => p !== undefined);
+  return parts.length > 0 ? parts.join(".") : undefined;
+}

package/src/transports/oci/oci-transport.ts

@@ -62,9 +62,8 @@ import {
  * payload gets a clear "republish" failure at the controller instead, while the
  * npm-backed majority, which ships none, is unaffected.
  */
-async function pullManifestLayer(ref: string): Promise<string> {
-  const { host, repo, reference, integrity } = parseOciRef(ref);
-  const client = new OciClient(host, repo);
+async function pullManifestLayer(ref: string, client: OciClient): Promise<string> {
+  const { reference, integrity } = parseOciRef(ref);
   const manifest = await client.pullManifest(reference);
   const layer =
     manifest.layers.find((l) => l.mediaType === TELO_MANIFEST_LAYER_MEDIA_TYPE) ??
@@ -108,18 +107,44 @@ async function pullManifestLayer(ref: string): Promise<string> {
 export class OciTransport implements Transport {
   readonly source: ManifestSource;
 
+  /** One read-side `OciClient` per `(host, repo)`, for this transport's lifetime.
+   *
+   *  The client caches bearer tokens per scope, but a client built per operation
+   *  discards that cache immediately — so every manifest and every blob paid its
+   *  own 401→challenge→token round trip, and with it a `~/.docker/config.json`
+   *  read and possibly a credential-helper subprocess. Pooling collapses those
+   *  to one handshake per repository. An expired token still self-heals:
+   *  `authedFetch` re-runs the challenge on a 401 and replaces the entry.
+   *
+   *  Owned by the instance rather than the module, so a second transport — a
+   *  test, or a second in-process kernel — never inherits another's credentials.
+   *  `defaultTransportRegistry` memoizes per registry URL, so the production
+   *  lifetime is unchanged. Publishing keeps its own client: it already reuses
+   *  one across the whole push, and a push-scoped token has no reason to
+   *  outlive the command. */
+  private readonly readClients = new Map<string, OciClient>();
+
   constructor() {
     this.source = {
       supports: (url) => this.supports(url),
       read: async (url) => {
-        const manifest = await pullManifestLayer(url);
         const { host, repo, reference } = parseOciRef(url);
+        const manifest = await pullManifestLayer(url, this.readClient(host, repo));
         return { text: manifest, source: `${OCI_SCHEME}${host}/${repo}@${reference}` };
       },
       resolveRelative: (base, relative) => this.resolveRelative(base, relative),
     };
   }
 
+  private readClient(host: string, repo: string): OciClient {
+    const key = `${host}/${repo}`;
+    const existing = this.readClients.get(key);
+    if (existing) return existing;
+    const client = new OciClient(host, repo);
+    this.readClients.set(key, client);
+    return client;
+  }
+
   supports(ref: string): boolean {
     return isOciRef(ref);
   }
@@ -159,7 +184,7 @@ export class OciTransport implements Transport {
 
   async listVersions(ref: string): Promise<string[] | null> {
     const { host, repo } = parseOciRef(ref);
-    const tags = await new OciClient(host, repo).listTags();
+    const tags = await this.readClient(host, repo).listTags();
     return tags;
   }
 
@@ -178,7 +203,7 @@ export class OciTransport implements Transport {
 
   async digest(ref: string): Promise<string | null> {
     const { host, repo, reference } = parseOciRef(ref);
-    return new OciClient(host, repo).headManifest(reference);
+    return this.readClient(host, repo).headManifest(reference);
   }
 
   /** Pull one payload layer by the `blob` digest the pinned index supplies. The
@@ -188,7 +213,7 @@ export class OciTransport implements Transport {
    *  expected `integrity`. */
   async fetchLayer(ref: string, blobDigest: string): Promise<PayloadFile[]> {
     const { host, repo } = parseOciRef(ref);
-    const tar = await new OciClient(host, repo).pullBlob(blobDigest);
+    const tar = await this.readClient(host, repo).pullBlob(blobDigest);
     // Verify the transfer against the digest that addressed it. A registry is
     // not trusted to return the blob that was asked for, and this is the only
     // place the pushed bytes exist — the content digest checked after extraction
@@ -212,7 +237,8 @@ export class OciTransport implements Transport {
    *  blob per import rather than a full artifact pull, and a corrupt payload
    *  upstream no longer surfaces here as a pinning failure. */
   async manifestHash(ref: string): Promise<string> {
-    const manifest = await pullManifestLayer(ref);
+    const { host, repo } = parseOciRef(ref);
+    const manifest = await pullManifestLayer(ref, this.readClient(host, repo));
     return `sha256-${await sha256Base64Url(new TextEncoder().encode(manifest))}`;
   }
 

package/src/transports/transport-registry.ts

@@ -82,10 +82,12 @@ export function defaultTransports(registryUrl?: string): Transport[] {
 const defaultRegistryCache = new Map<string, TransportRegistry>();
 
 /** A `TransportRegistry` seeded with {@link defaultTransports}, memoized per
- *  `registryUrl`. The default transports are stateless config (a fresh
- *  `OciClient` with its own token cache is created per OCI operation), so one
- *  shared instance per registry URL is safe — and avoids re-instantiating the
- *  whole set on hot paths like `cachePathForCanonical`. */
+ *  `registryUrl`. The default transports hold no per-call state, so one shared
+ *  instance per registry URL is safe — and avoids re-instantiating the whole set
+ *  on hot paths like `cachePathForCanonical`. It is also what gives
+ *  `OciTransport`'s per-instance read-client pool a process-wide lifetime here,
+ *  so the bearer-token cache survives across operations without the pool having
+ *  to be global. */
 export function defaultTransportRegistry(registryUrl?: string): TransportRegistry {
   const key = registryUrl ?? "";
   let cached = defaultRegistryCache.get(key);