@telorun/kernel 0.47.0 → 0.49.0

package/src/controllers/resource-definition/resource-template-controller.ts

@@ -61,8 +61,6 @@ export function createTemplateController(definition: {
   result?: Record<string, any>;
 }, definingContext: EvaluationContext): ControllerInstance {
   return {
-    schema: definition.schema ?? { type: "object", additionalProperties: true },
-
     create: async (resource: any, ctx: ResourceContext): Promise<ResourceInstance> => {
       // `self` is read lazily: Phase 5 injection mutates `resource`'s ref slots
       // (e.g. `connection: !ref Db` → the live instance) AFTER create() but before

package/src/kernel.ts

@@ -483,13 +483,17 @@ export class Kernel implements IKernel {
         );
       }
       // Bake the per-kind resource-config validators too. `_createInstance`
-      // compiles `controller.schema` (which falls back to the definition's own
-      // `schema`) for every resource at runtime — work this analyze-only pass
-      // otherwise skips because it stops before instantiation, leaving the
-      // runtime to recompile and fail to persist them on a read-only image.
+      // compiles the definition's `schema` for every resource at runtime — work
+      // this analyze-only pass otherwise skips because it stops before
+      // instantiation, leaving the runtime to recompile and fail to persist
+      // them on a read-only image.
       // Pre-compiling every `Telo.Definition` schema here writes them into the
-      // same content-addressed `__validators/` cache the runtime reads.
-      precompileDefinitionSchemas(staticManifests, this.sharedSchemaValidator);
+      // 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.
+      precompileDefinitionSchemas(staticManifests, this.sharedSchemaValidator, (def) =>
+        this.registry.resolverForDefinition(def),
+      );
       // Framework/builtin controller schemas (`Telo.Import`, `Telo.Definition`,
       // the module controller, …) aren't in the static manifests but are
       // validated per-resource at runtime just the same. They're registered by
@@ -1040,12 +1044,17 @@ export class Kernel implements IKernel {
         `Controller for ${kind} does not implement create method`,
       );
     }
-    if (!controller.schema?.type) {
-      throw new Error(`No schema defined for ${kind} controller`);
+    // The DEFINITION is the sole resource-config contract — a controller module
+    // cannot supply or override one. Keeping the schema on the manifest is what
+    // lets `telo check` see it, the validator warm bake it, and the editor render
+    // it; a code-side schema was invisible to all three and free to drift.
+    const definition = this.controllers.getDefinition(resolvedKind);
+    const configSchema = definition?.schema as Record<string, unknown> | undefined;
+    if (!configSchema?.type) {
+      throw new Error(`No schema defined for kind ${kind}`);
     }
 
     // Resolve eval paths from x-telo-eval annotations in the parent and own schema
-    const definition = this.controllers.getDefinition(resolvedKind);
     const parentDef = definition?.capability
       ? this.controllers.getDefinition(definition.capability)
       : undefined;
@@ -1063,8 +1072,8 @@ export class Kernel implements IKernel {
     // restoring the pre-CEL string view that the schema expects.
     try {
       this.sharedSchemaValidator
-        .compile(controller.schema)
-        .validate(stripCompiledValues(resource, controller.schema as Record<string, unknown>));
+        .compile(configSchema)
+        .validate(stripCompiledValues(resource, configSchema));
     } catch (error) {
       throw new RuntimeError(
         "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED",

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

@@ -1,3 +1,4 @@
+import { fetchOrThrow } from "@telorun/sdk";
 import { createHash } from "node:crypto";
 
 import { assertPublicEgress } from "../egress-guard.js";
@@ -32,6 +33,11 @@ export interface OciManifest {
   artifactType?: string;
   config: OciDescriptor;
   layers: OciDescriptor[];
+  /** Descriptive key/value metadata on the manifest. Telo projects the module's
+   *  declared provenance into the standard `org.opencontainers.image.*` keys —
+   *  the only metadata channel GHCR exposes, since it does not serve the
+   *  referrers API. */
+  annotations?: Record<string, string>;
 }
 
 function sha256Hex(bytes: Uint8Array): string {
@@ -104,7 +110,10 @@ export class OciClient {
     };
 
     const cached = this.tokenByScope.get(scope);
-    let res = await fetch(url, withToken(cached));
+    let res = await fetchOrThrow(url, withToken(cached), {
+      operation: "OCI registry request",
+      setting: "the oci:// ref host",
+    });
     if (res.status !== 401) return res;
 
     const challenge = res.headers.get("www-authenticate");
@@ -114,7 +123,10 @@ export class OciClient {
     this.tokenByScope.set(scope, token);
     // Drain the 401 body so the connection can be reused.
     await res.text().catch(() => {});
-    return fetch(url, withToken(token));
+    return fetchOrThrow(url, withToken(token), {
+      operation: "OCI registry request",
+      setting: "the oci:// ref host",
+    });
   }
 
   /** Exchange a bearer challenge for a token, authenticating to the token
@@ -136,7 +148,10 @@ export class OciClient {
       const basic = Buffer.from(`${cred.username}:${cred.password}`).toString("base64");
       headers.set("authorization", `Basic ${basic}`);
     }
-    const res = await fetch(tokenUrl.href, { headers });
+    const res = await fetchOrThrow(tokenUrl.href, { headers }, {
+      operation: "OCI registry auth",
+      setting: "the oci:// ref host",
+    });
     if (!res.ok) return null;
     const body = (await res.json()) as { token?: string; access_token?: string };
     return body.token ?? body.access_token ?? null;

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

@@ -1,12 +1,13 @@
 import {
   DEFAULT_MANIFEST_FILENAME,
   IntegrityError,
+  sha256Base64Url,
   verifyIntegrity,
   type ManifestSource,
 } from "@telorun/analyzer";
 
 import { computeFilesIntegrity, injectFilesIntegrity } from "../../bundle/files-integrity.js";
-import { readOwnerManifest } from "../../bundle/module-manifest.js";
+import { readOwnerManifest, type OwnerManifest } from "../../bundle/module-manifest.js";
 import { makeTarGz, readTarGz, toPayloadFiles } from "../../bundle/tar.js";
 import type {
   FetchedArtifact,
@@ -134,6 +135,39 @@ export class OciTransport implements Transport {
     return pullVerified(ref);
   }
 
+  /** Hashes the **UTF-8 encoding of the extracted `telo.yaml`**, which is what
+   *  `pullVerified` checks an inline `#sha256-…` pin against on the read path.
+   *
+   *  Cost note: a module is one tar blob, so there is no way to read `telo.yaml`
+   *  without pulling the whole artifact — including any `files:` payload — and
+   *  this path is deliberately uncached (a pin must hash what is published
+   *  *now*, not a cached copy). Two consequences for callers: pinning N imports
+   *  costs N full artifact pulls, and `pullVerified` also re-checks the
+   *  dependency's `filesIntegrity`, so a corrupt *payload* upstream surfaces
+   *  here as a pinning failure rather than a payload error. Both are acceptable
+   *  for publish-time pinning, where correctness beats latency and refusing to
+   *  pin against a corrupt dependency is the right outcome. */
+  async manifestHash(ref: string): Promise<string> {
+    const { manifest } = await pullVerified(ref);
+    return `sha256-${await sha256Base64Url(new TextEncoder().encode(manifest))}`;
+  }
+
+  /** Project a module's declared provenance onto the standard
+   *  `org.opencontainers.image.*` annotation keys. Descriptive only — nothing
+   *  addresses the artifact by these. Absent fields are omitted rather than
+   *  written empty, so the manifest carries only what the module declared. */
+  private static annotationsFor(identity: OwnerManifest): Record<string, string> {
+    const mapped: Array<[string, string | undefined]> = [
+      ["org.opencontainers.image.title", identity.name],
+      ["org.opencontainers.image.version", identity.version],
+      ["org.opencontainers.image.description", identity.description],
+      ["org.opencontainers.image.source", identity.repository],
+      ["org.opencontainers.image.licenses", identity.license],
+      ["org.opencontainers.image.documentation", identity.documentation],
+    ];
+    return Object.fromEntries(mapped.filter((e): e is [string, string] => Boolean(e[1])));
+  }
+
   async publish(
     destination: string,
     bundle: PublishBundle,
@@ -144,19 +178,19 @@ export class OciTransport implements Transport {
       throw new Error("OCI publish requires metadata.version (used as the tag).");
     }
 
-    // Destination is a full repo (`oci://host/repo`) or host-only
-    // (`oci://host`), which defaults the repo to `<namespace>/<name>`.
+    // Destination must be a full repo (`oci://host/repo`). Identity is the ref,
+    // so the repo is never derived from `metadata.namespace`/`name` — a
+    // metadata-derived path is wrong whenever the repo differs from the name,
+    // and would silently push to a namespace the publisher may not own.
     const afterScheme = destination.replace(/^oci:\/\//, "").replace(/\/+$/, "");
     const slash = afterScheme.indexOf("/");
     const host = slash > 0 ? afterScheme.slice(0, slash) : afterScheme;
-    let repo = slash > 0 ? afterScheme.slice(slash + 1) : "";
+    const repo = slash > 0 ? afterScheme.slice(slash + 1) : "";
     if (!repo) {
-      if (!identity.namespace || !identity.name) {
-        throw new Error(
-          `OCI publish to host-only '${destination}' needs metadata.namespace and metadata.name to default the repo.`,
-        );
-      }
-      repo = `${identity.namespace}/${identity.name}`;
+      throw new Error(
+        `OCI publish destination '${destination}' is host-only — it must name a full repository, ` +
+          `e.g. 'oci://${host || "ghcr.io"}/<org>/<name>'.`,
+      );
     }
     const tag = identity.version;
 
@@ -173,12 +207,14 @@ export class OciTransport implements Transport {
     const client = new OciClient(host, repo);
     const layerDigest = await client.pushBlob(tar);
     const config = await client.pushEmptyConfig();
+    const annotations = OciTransport.annotationsFor(identity);
     const manifest: OciManifest = {
       schemaVersion: 2,
       mediaType: OCI_MANIFEST_MEDIA_TYPE,
       artifactType: TELO_LAYER_MEDIA_TYPE,
       config,
       layers: [{ mediaType: TELO_LAYER_MEDIA_TYPE, digest: layerDigest, size: tar.length }],
+      ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
     };
     await client.pushManifest(tag, manifest);
 

package/src/transports/registry-transport.ts

@@ -9,6 +9,7 @@ import {
   splitIntegrity,
   type ManifestSource,
 } from "@telorun/analyzer";
+import { fetchOrThrow } from "@telorun/sdk";
 import { createHash } from "crypto";
 
 import { computeFilesIntegrity, injectFilesIntegrity } from "../bundle/files-integrity.js";
@@ -159,7 +160,11 @@ export class RegistryTransport implements Transport {
     const { modulePath } = parseModuleRef(ref);
     const url = `${this.registryUrl.replace(/\/+$/, "")}/${modulePath}`;
     await assertPublicEgress(url);
-    const res = await fetch(url, { headers: { accept: "application/json" } });
+    const res = await fetchOrThrow(
+      url,
+      { headers: { accept: "application/json" } },
+      { operation: "Registry version list", setting: "--registry / TELO_REGISTRY" },
+    );
     if (res.status === 404) return null;
     if (!res.ok) {
       throw new Error(`Registry returned ${res.status} ${res.statusText} for ${modulePath}`);
@@ -168,22 +173,31 @@ export class RegistryTransport implements Transport {
     return Array.isArray(body.versions) ? body.versions : [];
   }
 
-  async digest(ref: string): Promise<string | null> {
-    // Mirrors the sources' fetch-URL derivation: a direct URL points at (or
-    // contains) the YAML file; a bare registry ref folds into the registry
-    // layout. The digest is Telo's canonical hash over the `telo.yaml` bytes.
+  /** Mirrors the sources' fetch-URL derivation: a direct URL points at (or
+   *  contains) the YAML file; a bare registry ref folds into the registry
+   *  layout. `null` when this transport does not own the ref's shape. */
+  private manifestUrl(ref: string): string | null {
     const { base } = splitIntegrity(ref);
-    let fetchUrl: string;
     if (base.startsWith("http://") || base.startsWith("https://")) {
-      fetchUrl = base.includes(".yaml") ? base : `${base}/${DEFAULT_MANIFEST_FILENAME}`;
-    } else if (isRegistryRef(ref)) {
+      return base.includes(".yaml") ? base : `${base}/${DEFAULT_MANIFEST_FILENAME}`;
+    }
+    if (isRegistryRef(ref)) {
       const { modulePath, version } = parseModuleRef(ref);
-      fetchUrl = `${this.registryUrl.replace(/\/+$/, "")}/${modulePath}/${version}/${DEFAULT_MANIFEST_FILENAME}`;
-    } else {
-      return null;
+      return `${this.registryUrl.replace(/\/+$/, "")}/${modulePath}/${version}/${DEFAULT_MANIFEST_FILENAME}`;
     }
+    return null;
+  }
+
+  async digest(ref: string): Promise<string | null> {
+    // The digest is Telo's canonical hash over the `telo.yaml` bytes — the same
+    // value `manifestHash` returns, but absent-is-null rather than a throw.
+    const fetchUrl = this.manifestUrl(ref);
+    if (!fetchUrl) return null;
     await assertPublicEgress(fetchUrl);
-    const res = await fetch(fetchUrl);
+    const res = await fetchOrThrow(fetchUrl, undefined, {
+      operation: "Registry manifest read",
+      setting: "--registry / TELO_REGISTRY",
+    });
     if (res.status === 404) return null;
     if (!res.ok) {
       throw new Error(`Registry returned ${res.status} ${res.statusText} for ${fetchUrl}`);
@@ -192,6 +206,25 @@ export class RegistryTransport implements Transport {
     return `sha256-${await sha256Base64Url(bytes)}`;
   }
 
+  /** Hashes the **raw response bytes**, which is exactly what `verifiedFetch`
+   *  checks an inline `#sha256-…` pin against on the read path. */
+  async manifestHash(ref: string): Promise<string> {
+    const fetchUrl = this.manifestUrl(ref);
+    if (!fetchUrl) {
+      throw new Error(`cannot hash non-remote import '${ref}'`);
+    }
+    await assertPublicEgress(fetchUrl);
+    const res = await fetchOrThrow(fetchUrl, undefined, {
+      operation: "Registry manifest hash",
+      setting: "--registry / TELO_REGISTRY",
+    });
+    if (!res.ok) {
+      throw new Error(`fetch ${fetchUrl}: ${res.status} ${res.statusText}`);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    return `sha256-${await sha256Base64Url(bytes)}`;
+  }
+
   async fetchArtifact(ref: string): Promise<FetchedArtifact> {
     // `read` verifies the manifest bytes against the inline `#sha256-...` hash.
     const { text: manifest, source } = await this.source.read(ref);
@@ -201,7 +234,10 @@ export class RegistryTransport implements Transport {
     // The payload rides beside the manifest as `module.tar.gz`.
     const tarUrl = source.replace(/\/telo\.yaml$/, "/module.tar.gz");
     await assertPublicEgress(tarUrl);
-    const res = await fetch(tarUrl);
+    const res = await fetchOrThrow(tarUrl, undefined, {
+      operation: "Module payload download",
+      setting: "--registry / TELO_REGISTRY",
+    });
     if (!res.ok) {
       throw new Error(`could not fetch bundle ${tarUrl}: ${res.status} ${res.statusText}`);
     }
@@ -263,7 +299,11 @@ export class RegistryTransport implements Transport {
     for (let attempt = 1; attempt <= MAX_PUSH_ATTEMPTS; attempt++) {
       networkErr = null;
       try {
-        res = await fetch(url, { method: "PUT", headers, body });
+        res = await fetchOrThrow(
+          url,
+          { method: "PUT", headers, body },
+          { operation: "Registry publish", setting: "--registry / TELO_REGISTRY" },
+        );
       } catch (err) {
         networkErr = err;
         res = null;

package/src/transports/transport.ts

@@ -99,6 +99,26 @@ export interface Transport {
    *  digest per version and re-checks it on every track. */
   digest(ref: string): Promise<string | null>;
 
+  /** Telo's inline integrity hash (`sha256-<base64url>`) for the `telo.yaml`
+   *  `ref` resolves to — the value written as a `#sha256-…` pin by `telo
+   *  publish` and re-pinned by `telo upgrade`. Throws when the ref does not
+   *  resolve; callers decide whether that is fatal (`--frozen`) or best-effort.
+   *
+   *  This is on the interface, not computed by the caller, because *what gets
+   *  hashed* is transport-specific and must match exactly what that transport's
+   *  own `source.read()` verifies — otherwise a pin written at publish fails
+   *  verification at import. HTTP/registry hash the raw response bytes;
+   *  OCI hashes the UTF-8 encoding of the `telo.yaml` extracted from the tar
+   *  layer. A caller cannot know which, so a caller-side scheme branch silently
+   *  degrades the moment a transport is added — which is exactly how `oci://`
+   *  refs came to be published unpinned.
+   *
+   *  Distinct from `digest()`: that is an opaque transport-native content id for
+   *  change detection, never written into a manifest or compared across
+   *  transports. This is the portable, cross-transport hash Telo itself
+   *  verifies. */
+  manifestHash(ref: string): Promise<string>;
+
   /** Push `bundle` to `destination` (a base ref / repo whose scheme this
    *  transport owns), pinning the payload and writing the transport-native
    *  artifact shape. Throws on failure. Used by `telo publish`. */