@telorun/kernel 0.42.0 → 0.44.0

package/src/bundle/tar.ts

@@ -0,0 +1,78 @@
+import { extract as tarExtract, pack as tarPack } from "tar-stream";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { Readable } from "node:stream";
+
+import type { PayloadFile } from "./files-integrity.js";
+
+export interface BundleEntry {
+  /** POSIX-relative path inside the archive (e.g. `telo.yaml`, `public/app.js`). */
+  name: string;
+  content: Buffer | string;
+}
+
+/** Normalize decoded tar entries to `PayloadFile`s (Buffer-backed content) —
+ *  the fixed step both transports run after `readTarGz`. */
+export function toPayloadFiles(entries: BundleEntry[]): PayloadFile[] {
+  return entries.map((e) => ({
+    name: e.name,
+    content: typeof e.content === "string" ? Buffer.from(e.content) : e.content,
+  }));
+}
+
+/**
+ * Pack `entries` into a gzipped tar (`module.tar.gz`) — the module-artifact
+ * writer shared by `telo publish` and the transports. Artifacts are small (a
+ * manifest plus a built frontend), so buffering the whole archive before gzip
+ * is fine. (Distinct from `apps/k8s-runner/src/tar.ts`, which is coupled to
+ * `@telorun/runner-core`'s `RunBundle`.)
+ */
+export async function makeTarGz(entries: BundleEntry[]): Promise<Buffer> {
+  const pack = tarPack();
+  const chunks: Buffer[] = [];
+  pack.on("data", (c: Buffer) => chunks.push(c));
+
+  const done = new Promise<void>((resolve, reject) => {
+    pack.on("end", resolve);
+    pack.on("error", reject);
+  });
+
+  for (const entry of entries) {
+    const buf = typeof entry.content === "string" ? Buffer.from(entry.content, "utf-8") : entry.content;
+    await new Promise<void>((resolve, reject) => {
+      pack.entry({ name: entry.name }, buf, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+  pack.finalize();
+  await done;
+
+  return gzipSync(Buffer.concat(chunks));
+}
+
+/** Decompress + untar a `module.tar.gz` buffer into its file entries. */
+export async function readTarGz(buf: Buffer): Promise<BundleEntry[]> {
+  const tar = gunzipSync(buf);
+  const ex = tarExtract();
+  const entries: BundleEntry[] = [];
+
+  await new Promise<void>((resolve, reject) => {
+    ex.on("entry", (header, stream, next) => {
+      if (header.type !== "file") {
+        stream.on("end", next);
+        stream.resume();
+        return;
+      }
+      const chunks: Buffer[] = [];
+      stream.on("data", (c: Buffer) => chunks.push(c));
+      stream.on("end", () => {
+        entries.push({ name: header.name, content: Buffer.concat(chunks) });
+        next();
+      });
+      stream.on("error", reject);
+    });
+    ex.on("finish", resolve);
+    ex.on("error", reject);
+    Readable.from(tar).pipe(ex);
+  });
+
+  return entries;
+}

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

@@ -1,12 +1,21 @@
 import type {
   ControllerContext,
   ResourceContext,
+  ResourceDefinition as ResourceDefinitionManifest,
   ResourceInstance,
   RuntimeResource,
 } from "@telorun/sdk";
+import { RuntimeError } from "@telorun/sdk";
+import {
+  controllerBearingAncestor,
+  hasOwnControllerOrTemplate,
+  inheritedCapability,
+  type DefResolver,
+} from "@telorun/analyzer";
 import { ControllerLoader } from "../../controller-loader.js";
 import { formatAjvErrors, validateResourceDefinition } from "../../manifest-schemas.js";
 import { createTemplateController } from "./resource-template-controller.js";
+import { createInheritedController } from "./resource-inherited-controller.js";
 
 type ResourceDefinitionResource = RuntimeResource & {
   kind: "Telo.Definition";
@@ -17,6 +26,8 @@ type ResourceDefinitionResource = RuntimeResource & {
   };
   schema: Record<string, any>;
   capability?: string;
+  extends?: string;
+  base?: Record<string, any>;
   controllers?: Array<string>;
   provide?: unknown;
 };
@@ -31,6 +42,60 @@ class ResourceDefinition implements ResourceInstance {
   constructor(readonly resource: ResourceDefinitionResource) {}
 
   async init(ctx: ResourceContext) {
+    const definingCtx = ctx.moduleContext;
+    // Resolve an `extends`/kind target (alias or canonical form) to its
+    // definition against the DEFINING library's scope — where the `extends`
+    // alias was declared.
+    const resolveDef: DefResolver = (kind) => {
+      let canonical = kind;
+      try {
+        canonical = definingCtx.resolveKind(kind);
+      } catch {
+        // ungated / unqualified — fall back to the raw kind below
+      }
+      return definingCtx.getDefinition?.(canonical) ?? definingCtx.getDefinition?.(kind);
+    };
+
+    // Inherited-controller delegation: a definition that `extends` a concrete
+    // kind, declares no own `controllers:` / template body, inherits the parent
+    // controller by delegation and maps its config via `base:`.
+    if (this.resource.extends && !hasOwnControllerOrTemplate(this.resource as ResourceDefinitionManifest)) {
+      const parentDef = resolveDef(this.resource.extends);
+      if (!parentDef) {
+        // The parent's Telo.Definition (and thus its controller) isn't loaded
+        // yet — defer; the multi-pass init loop retries once its import resolves.
+        throw new RuntimeError(
+          "ERR_LOCAL_REF_PENDING",
+          `Telo.Definition '${this.resource.metadata.name}': 'extends' target '${this.resource.extends}' is not loaded yet.`,
+        );
+      }
+      if (controllerBearingAncestor(this.resource as ResourceDefinitionManifest, resolveDef)) {
+        // Capability is inherited and immutable — stamp the resolved capability
+        // so every consumer that reads `definition.capability` (compile-CEL eval
+        // paths, `capabilityOf`, lifecycle role) sees the effective role without
+        // re-walking `extends`.
+        if (!this.resource.capability) {
+          const inherited = inheritedCapability(this.resource as ResourceDefinitionManifest, resolveDef);
+          if (inherited) this.resource.capability = inherited;
+        }
+        const controllerInstance = createInheritedController(
+          this.resource as ResourceDefinitionManifest,
+          definingCtx,
+          resolveDef,
+        );
+        ctx.registerDefinition(this.resource);
+        await ctx.registerController(
+          this.resource.metadata.module,
+          this.resource.metadata.name,
+          controllerInstance,
+        );
+        return;
+      }
+      // Otherwise the chain reaches no controller-bearing concrete ancestor
+      // (e.g. it implements a pure abstract) — fall through to the normal
+      // template / controller handling below.
+    }
+
     if (!this.resource.controllers?.length) {
       if (this.resource.capability === "Telo.Provider" && this.resource.provide == null) {
         throw new Error(

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

@@ -0,0 +1,167 @@
+import type {
+  ControllerInstance,
+  EvaluationContext,
+  ResourceContext,
+  ResourceDefinition,
+  ResourceInstance,
+} from "@telorun/sdk";
+import { isCompiledValue } from "@telorun/sdk";
+import {
+  buildReferenceFieldMap,
+  effectiveAuthorSchema,
+  isRefEntry,
+  type DefResolver,
+} from "@telorun/analyzer";
+import { isRefSentinel } from "@telorun/templating";
+
+/** Typed internal seam implemented by the concrete `ResourceContextImpl`: runs
+ *  the kernel's create phase for the parent-kind manifest and returns the native
+ *  parent instance (or null when the parent controller isn't registered yet — a
+ *  retry, same as `_createInstance`). Off the public SDK surface, like
+ *  `registerLazyController`. */
+export interface InheritedInstanceHost {
+  createInheritedInstance(
+    evalContext: EvaluationContext,
+    resource: Record<string, unknown>,
+  ): Promise<ResourceInstance | null>;
+}
+
+/** Matches a CEL source that is exactly a `self.<path>` member access — resolved
+ *  by direct navigation so live resource instances (which CEL's output type
+ *  checker rejects) can flow through `base:` untouched. */
+const SELF_PATH = /^self((?:\.[A-Za-z_$][\w$]*)+)$/;
+
+interface Snapshotable {
+  snapshot(): Record<string, unknown>;
+}
+const hasSnapshot = (v: unknown): v is Snapshotable =>
+  !!v && typeof (v as { snapshot?: unknown }).snapshot === "function";
+
+/** Resolves a reference-slot value to its live instance, or undefined when the
+ *  referenced resource isn't initialized yet. A value that is already a live
+ *  instance (has `snapshot()`) passes through. Post Phase-2.5 a slot holds a
+ *  `{kind, name, alias?}` object; a raw `!ref` sentinel (only reachable behind a
+ *  hidden `$ref` slot) is normalized through the sanctioned `ctx.resolveChildren`
+ *  so the reference grammar (alias/Self splitting) stays in one place. */
+function resolveRefSlot(value: unknown, ctx: ResourceContext): ResourceInstance | undefined {
+  if (hasSnapshot(value)) return value as unknown as ResourceInstance;
+  let name: string | undefined;
+  let alias: string | undefined;
+  if (isRefSentinel(value)) {
+    const ref = ctx.resolveChildren(value) as { name: string; alias?: string };
+    name = ref.name;
+    alias = ref.alias;
+  } else if (value && typeof value === "object") {
+    const ref = value as { name?: unknown; alias?: unknown };
+    if (typeof ref.name === "string") {
+      name = ref.name;
+      alias = typeof ref.alias === "string" ? ref.alias : undefined;
+    }
+  }
+  if (!name) return undefined;
+  const instance =
+    alias && alias !== "Self"
+      ? ctx.moduleContext.resolveImportedInstance(alias, name)
+      : (ctx.moduleContext.resourceInstances.get(name)?.instance as ResourceInstance | undefined);
+  return instance ?? undefined;
+}
+
+/** Expand a `base:` node against `self`. Self-only CEL resolves to literals now;
+ *  a pure `self.<path>` access is navigated directly so live instances pass
+ *  through. */
+function expandBaseNode(value: unknown, self: Record<string, unknown>, ctx: EvaluationContext): unknown {
+  if (isCompiledValue(value)) {
+    const src = typeof value.source === "string" ? value.source.trim() : "";
+    const m = src.match(SELF_PATH);
+    if (m) {
+      let cur: unknown = self;
+      for (const key of m[1].split(".").slice(1)) {
+        cur = (cur as Record<string, unknown> | undefined)?.[key];
+      }
+      return cur;
+    }
+    return ctx.expandWith(value, { self });
+  }
+  if (Array.isArray(value)) return value.map((v) => expandBaseNode(v, self, ctx));
+  if (value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = expandBaseNode(v, self, ctx);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Controller for a definition that inherits its controller by delegation — it
+ * `extends` a concrete kind, declares no own `controllers:` / template body, and
+ * maps the parent's config via `base:`. `create()` evaluates `base:` against the
+ * child instance's config (`self`, with reference slots resolved to live
+ * instances) and constructs the parent kind through {@link InheritedInstanceHost},
+ * returning that native parent instance verbatim so the child duck-types as its
+ * parent (e.g. inherits `.snapshot()`).
+ */
+export function createInheritedController(
+  definition: ResourceDefinition,
+  definingContext: EvaluationContext,
+  resolveDef: DefResolver,
+): ControllerInstance {
+  const authorSchema = effectiveAuthorSchema(definition, resolveDef);
+  const parentKind = definition.extends;
+  if (!parentKind) {
+    throw new Error(
+      `Telo.Definition '${definition.metadata.name}': inherited controller requires an 'extends' target.`,
+    );
+  }
+  const base = definition.base;
+
+  // Top-level reference fields on the author-facing schema — resolved to live
+  // instances before `base:` runs so a `!cel "self.<ref>"` passthrough forwards
+  // the live parent instance (e.g. a `client` into an inherited Http.Request).
+  const refFieldPaths: string[] = [];
+  for (const [path, entry] of buildReferenceFieldMap(authorSchema)) {
+    if (isRefEntry(entry) && !path.includes(".") && !path.includes("[")) refFieldPaths.push(path);
+  }
+
+  return {
+    schema: authorSchema,
+
+    create: async (resource: any, ctx: ResourceContext): Promise<ResourceInstance | null> => {
+      const self: Record<string, unknown> = { ...resource, name: resource.metadata.name };
+      for (const path of refFieldPaths) {
+        const raw = (resource as Record<string, unknown>)[path];
+        if (raw == null) continue;
+        const live = resolveRefSlot(raw, ctx);
+        // A reference that is set but hasn't resolved yet means the dependency
+        // isn't initialized — defer via the retry signal, like _createInstance.
+        if (!live) return null;
+        self[path] = live;
+      }
+
+      // With `base:`, it maps `self` onto the parent's (narrowed) config. Without
+      // it, the child is a pure additive extension: it carries the parent's config
+      // fields directly, so forward them (reference slots already resolved to live
+      // instances in `self`), minus the reserved keys.
+      let parentConfig: Record<string, unknown>;
+      if (base != null) {
+        parentConfig = expandBaseNode(base, self, definingContext) as Record<string, unknown>;
+      } else {
+        const { kind: _kind, metadata: _metadata, name: _name, ...config } = self;
+        parentConfig = config;
+      }
+      const parentResource: Record<string, unknown> = {
+        kind: parentKind,
+        metadata: { ...resource.metadata },
+        ...parentConfig,
+      };
+      const host = ctx as unknown as InheritedInstanceHost;
+      if (typeof (host as { createInheritedInstance?: unknown }).createInheritedInstance !== "function") {
+        throw new Error(
+          `Telo.Definition '${definition.metadata.name}': inherited controller requires a ResourceContext host that implements createInheritedInstance().`,
+        );
+      }
+      return host.createInheritedInstance(definingContext, parentResource);
+    },
+  };
+}

package/src/index.ts

@@ -10,6 +10,28 @@ export {
   writeManifestCache,
 } from "./manifest-sources/local-manifest-cache-source.js";
 export { MemorySource } from "./manifest-sources/memory-source.js";
+export type { Transport } from "./transports/transport.js";
+export { RegistryTransport } from "./transports/registry-transport.js";
+export { OciTransport } from "./transports/oci/oci-transport.js";
+export { OciClient } from "./transports/oci/oci-client.js";
+export { isOciRef, parseOciRef, type ParsedOciRef } from "./transports/oci/oci-ref.js";
+export {
+  TransportRegistry,
+  defaultTransports,
+  defaultTransportRegistry,
+} from "./transports/transport-registry.js";
+export { makeTarGz, readTarGz, type BundleEntry } from "./bundle/tar.js";
+export {
+  computeFilesIntegrity,
+  injectFilesIntegrity,
+  type PayloadFile,
+} from "./bundle/files-integrity.js";
+export type {
+  FetchedArtifact,
+  PublishBundle,
+  PublishResult,
+  PublishOptions,
+} from "./transports/transport.js";
 export { ExecutionContext } from "./execution-context.js";
 export { Kernel, type KernelOptions } from "./kernel.js";
 export { nodeCelHandlers } from "./cel-handlers.js";

package/src/kernel.ts

@@ -1,7 +1,6 @@
 import {
   AnalysisRegistry,
   buildEvalPaths,
-  defaultSources,
   flattenForAnalyzer,
   flattenLoadedModule,
   isModuleKind,
@@ -48,6 +47,7 @@ import {
 import {
   resolveCacheRoot,
 } from "./manifest-sources/local-manifest-cache-source.js";
+import { defaultTransportRegistry } from "./transports/transport-registry.js";
 import {
   collectDeclaredEnvKeys,
   precompileApplicationEnvSchemas,
@@ -156,7 +156,12 @@ export class Kernel implements IKernel {
     this.env = options.env ?? hostEnv();
     this.argv = options.argv ?? [];
     this.registryUrl = options.registryUrl;
-    this.loader = new Loader(defaultSources(this.registryUrl), { celHandlers: nodeCelHandlers });
+    // Resolution sources come from the transport registry, so a scheme-owning
+    // transport (OCI, later S3) joins the loader's dispatch chain by being
+    // registered — no source-chain edits here.
+    this.loader = new Loader(defaultTransportRegistry(this.registryUrl).sources(), {
+      celHandlers: nodeCelHandlers,
+    });
     for (const source of options.sources) {
       this.loader.register(source);
     }
@@ -1113,6 +1118,23 @@ export class Kernel implements IKernel {
     return { instance, ctx, resource: processedResource };
   }
 
+  /**
+   * Create phase for an inherited (concrete-`extends`) definition's parent: runs
+   * the ordinary create pipeline (controller resolution + lazy load, schema
+   * validation, compile-CEL expansion, ctx creation) for the parent-kind
+   * manifest built from `base:`, and returns the native parent instance. The
+   * inherited child's controller returns this verbatim so the child duck-types
+   * as its parent. Null means the parent controller isn't registered yet — the
+   * caller propagates it as the create-phase retry signal.
+   */
+  async createInheritedInstance(
+    evalContext: IEvaluationContext,
+    resource: ResourceManifest,
+  ): Promise<ResourceInstance | null> {
+    const created = await this._createInstance(evalContext, resource);
+    return created?.instance ?? null;
+  }
+
   /**
    * Phase 5 — Inject live instances into reference fields of a resource config.
    *

package/src/manifest-sources/local-manifest-cache-source.ts

@@ -1,17 +1,14 @@
 import { splitIntegrity, verifyIntegrity, type LoadedGraph, type ManifestSource } from "@telorun/analyzer";
-import { createHash } from "crypto";
 import { statSync } from "fs";
 import * as fs from "fs/promises";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 
 import { hostEnv } from "../host-env.js";
+import { TransportRegistry, defaultTransportRegistry } from "../transports/transport-registry.js";
 
 const CACHE_SUBDIR = ".telo/manifests";
-const HTTP_NAMESPACE = "__http";
-const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
 const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
-const QUERY_HASH_LENGTH = 12;
 
 /** Verify that `candidate` resolves to a path under `root`. Returns the
  *  candidate path on success, `null` when any segment escapes the root.
@@ -27,104 +24,22 @@ function joinUnder(root: string, ...segments: string[]): string | null {
   return candidate;
 }
 
-/** Mirror `HttpSource.read`'s `fetchUrl` derivation: when the URL does not
- *  already point at a YAML file, append `/telo.yaml`. Used by both the
- *  reader and writer so a raw import URL and the canonical source it
- *  resolves to map to the same cache path. */
-function normalizePathname(url: string, parsed: URL): string {
-  let pathname = parsed.pathname;
-  if (!url.includes(".yaml")) {
-    pathname = pathname.endsWith("/")
-      ? `${pathname}${DEFAULT_MANIFEST_FILENAME}`
-      : `${pathname}/${DEFAULT_MANIFEST_FILENAME}`;
-  }
-  return pathname;
-}
-
-/** Compute a short hash of `search + hash` so two URLs that differ only in
- *  query / fragment do not collide at the same cache path. Inserted before
- *  the final extension so the filename stays readable. */
-function disambiguatePath(pathname: string, search: string, hash: string): string {
-  if (!search && !hash) return pathname;
-  const digest = createHash("sha256")
-    .update(search + hash)
-    .digest("hex")
-    .slice(0, QUERY_HASH_LENGTH);
-  const ext = path.extname(pathname);
-  const base = pathname.slice(0, pathname.length - ext.length);
-  return `${base}.${digest}${ext}`;
-}
-
 /** Single source of truth for URL → cache path. Used identically by the
  *  reader (cache lookup) and writer (install-time persistence). For any
- *  given import URL — registry ref, direct registry URL, or arbitrary
- *  HTTP — both sides land on the same file.
+ *  given import ref — registry ref, direct registry URL, arbitrary HTTP, or
+ *  (once registered) `oci://` — both sides land on the same file, because the
+ *  owning transport decides the layout via {@link Transport.cacheLocation}.
  *
- *  Returns `null` for unsupported URLs (file://, memory://, relative paths)
- *  or for path-traversal attempts that would escape `cacheRoot`. */
+ *  Returns `null` for unsupported refs (file://, memory://, relative paths) or
+ *  for path-traversal attempts that would escape `cacheRoot`. */
 function cachePathForUrl(
   rawUrl: string,
   cacheRoot: string,
-  registryUrl: string,
+  transports: TransportRegistry,
 ): string | null {
-  // Strip any inline integrity fragment so the cache path is derived from the
-  // bare ref/URL — the hash never participates in on-disk keying.
-  const url = splitIntegrity(rawUrl).base;
-  const trimmedRegistry = registryUrl.replace(/\/+$/, "");
-
-  // 1. Registry ref form: namespace/name@version
-  if (
-    !url.startsWith("http://") &&
-    !url.startsWith("https://") &&
-    !url.startsWith("/") &&
-    !url.startsWith(".") &&
-    !url.startsWith("file://") &&
-    !url.startsWith("memory://") &&
-    url.includes("@") &&
-    url.includes("/")
-  ) {
-    const atIdx = url.lastIndexOf("@");
-    if (atIdx <= 0 || atIdx === url.length - 1) return null;
-    const modulePath = url.slice(0, atIdx);
-    if (!modulePath.includes("/")) return null;
-    const version = url.slice(atIdx + 1).replace(/^v/, "");
-    if (!version) return null;
-    return joinUnder(cacheRoot, modulePath, version, DEFAULT_MANIFEST_FILENAME);
-  }
-
-  // 2. HTTP(S) URL — could be a direct registry URL or arbitrary external.
-  if (url.startsWith("http://") || url.startsWith("https://")) {
-    let parsed: URL;
-    try {
-      parsed = new URL(url);
-    } catch {
-      return null;
-    }
-    const pathname = normalizePathname(url, parsed);
-
-    // 2a. URL is on the configured registry, with no query/fragment:
-    //     fold into the registry layout so the writer that received a
-    //     registry-ref canonical and the reader that sees a direct URL
-    //     both resolve to the same file.
-    const normalizedUrl = `${parsed.protocol}//${parsed.host}${pathname}`;
-    if (
-      !parsed.search &&
-      !parsed.hash &&
-      (normalizedUrl === trimmedRegistry || normalizedUrl.startsWith(`${trimmedRegistry}/`))
-    ) {
-      const rel = normalizedUrl.slice(trimmedRegistry.length + 1);
-      if (!rel) return null;
-      return joinUnder(cacheRoot, ...rel.split("/"));
-    }
-
-    // 2b. Arbitrary HTTP(S) URL → __http subtree, with a short query-hash
-    //     suffix when query / fragment are present to prevent collisions.
-    const cleanPath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
-    const disambiguated = disambiguatePath(cleanPath, parsed.search, parsed.hash);
-    return joinUnder(cacheRoot, HTTP_NAMESPACE, parsed.host, ...disambiguated.split("/"));
-  }
-
-  return null;
+  const segments = transports.cacheLocation(rawUrl);
+  if (!segments) return null;
+  return joinUnder(cacheRoot, ...segments);
 }
 
 /**
@@ -136,7 +51,7 @@ function cachePathForUrl(
  */
 export class LocalManifestCacheSource implements ManifestSource {
   private readonly cacheRoot: string;
-  private readonly registryUrl: string;
+  private readonly transports: TransportRegistry;
 
   constructor(
     entryDir: string,
@@ -147,7 +62,7 @@ export class LocalManifestCacheSource implements ManifestSource {
     // single `resolveCacheRoot` (honours `TELO_CACHE_DIR`); when absent we fall
     // back to the entry-anchored default so library/test callers are unchanged.
     this.cacheRoot = manifestsDir ?? path.join(entryDir, CACHE_SUBDIR);
-    this.registryUrl = registryUrl;
+    this.transports = defaultTransportRegistry(registryUrl);
   }
 
   supports(url: string): boolean {
@@ -184,7 +99,7 @@ export class LocalManifestCacheSource implements ManifestSource {
   }
 
   private tryMap(url: string): string | null {
-    const candidate = cachePathForUrl(url, this.cacheRoot, this.registryUrl);
+    const candidate = cachePathForUrl(url, this.cacheRoot, this.transports);
     if (!candidate) return null;
     // Require a regular file. A directory, dangling symlink, or stat failure
     // (ENOENT, EACCES, EISDIR-on-component) all fall through as a cache miss
@@ -213,7 +128,7 @@ export function cachePathForCanonical(
   manifestsDir?: string,
 ): string | null {
   const cacheRoot = manifestsDir ?? path.join(entryDir, CACHE_SUBDIR);
-  return cachePathForUrl(canonicalSource, cacheRoot, registryUrl);
+  return cachePathForUrl(canonicalSource, cacheRoot, defaultTransportRegistry(registryUrl));
 }
 
 /**

package/src/resource-context.ts

@@ -412,6 +412,20 @@ export class ResourceContextImpl implements ResourceContext {
     this.kernel.registerLazyController(moduleName, kindName, fingerprint, load);
   }
 
+  /**
+   * Run the create phase for an inherited (concrete-`extends`) definition's
+   * parent kind, returning the native parent instance (or null when the parent
+   * controller isn't registered yet — a retry). A typed internal seam for the
+   * inherited-controller delegation; off the public SDK `ResourceContext`
+   * surface, like `registerLazyController`.
+   */
+  createInheritedInstance(
+    evalContext: IEvaluationContext,
+    resource: Record<string, unknown>,
+  ): Promise<ResourceInstance | null> {
+    return this.kernel.createInheritedInstance(evalContext, resource as ResourceManifest);
+  }
+
   registerDefinition(def: any) {
     this.kernel.registerResourceDefinition(def);
   }