@telorun/kernel 0.58.0 → 0.60.0

package/src/index.ts

@@ -23,11 +23,19 @@ export {
 export { makeTarGz, readTarGz, type BundleEntry } from "./bundle/tar.js";
 export {
   computeFilesIntegrity,
-  injectFilesIntegrity,
+  injectLayerIndex,
   type PayloadFile,
 } from "./bundle/files-integrity.js";
+export {
+  ModuleArtifact,
+  moduleArtifactFor,
+  moduleDirectoryFor,
+  hostPlatformTarget,
+  type MaterializedLayer,
+} from "./bundle/module-artifact.js";
+export { readOwnerManifest, type OwnerManifest } from "./bundle/module-manifest.js";
 export type {
-  FetchedArtifact,
+  PayloadLayer,
   PublishBundle,
   PublishResult,
   PublishOptions,

package/src/kernel.ts

@@ -49,8 +49,16 @@ import {
   writeAnalysisStamp,
 } from "./manifest-sources/analysis-stamp.js";
 import {
+  cachePathForCanonical,
   resolveCacheRoot,
+  resolveEntryDir,
 } from "./manifest-sources/local-manifest-cache-source.js";
+import { readOwnerManifest } from "./bundle/module-manifest.js";
+import {
+  moduleArtifactFor,
+  moduleDirectoryFor,
+  type ModuleArtifact,
+} from "./bundle/module-artifact.js";
 import { defaultTransportRegistry } from "./transports/transport-registry.js";
 import {
   collectDeclaredEnvKeys,
@@ -131,6 +139,9 @@ export class Kernel implements IKernel {
   /** The `.telo` cache root for this load, resolved once in `load()` and
    *  threaded to the validator, analysis stamp, and npm install root. */
   private _cacheRoot?: string | null;
+  /** Per-module artifact handles, keyed by canonical manifest source. Rebuilt on
+   *  every `load()`; empty for a graph of purely local / manifest-only modules. */
+  private readonly moduleArtifacts = new Map<string, ModuleArtifact>();
   private _loadedGraph?: LoadedGraph;
   // Lifecycle state — guards boot/runTargets/teardown/invoke transitions.
   // teardown() is the only idempotent method; everything else throws on misuse.
@@ -425,6 +436,7 @@ export class Kernel implements IKernel {
       );
     }
     this._loadedGraph = analysisGraph;
+    this.buildModuleArtifacts(analysisGraph, manifestsDir);
     // Version reconciliation: an incompatible major mismatch is fatal (the
     // hoist override would silently run the wrong major); a same-major hoist is
     // advisory — the override already redirects every importer to the winner.
@@ -918,6 +930,60 @@ export class Kernel implements IKernel {
     return this._cacheRoot ? `${this._cacheRoot}/npm` : undefined;
   }
 
+  /**
+   * Build one {@link ModuleArtifact} per loaded module that ships a payload.
+   *
+   * Here, and not inside a controller loader, because this is the only point
+   * where both halves are in hand: the **pinned** ref the importer wrote
+   * (`requestedUrl`, integrity fragment included) and the manifest text that has
+   * already been verified against it. A loader sees only the canonical base URI,
+   * which carries no `#sha256-`, so a loader that fetched for itself would have
+   * to re-read the index off the cache directory — verification downgraded from
+   * "anchored at the importer's pin" to "trust whatever is on disk".
+   *
+   * Keyed by canonical `source`, which is what a definition's `metadata.source`
+   * carries, so a controller resolution can find its module's artifact.
+   *
+   * The trigger is "this manifest carries a `layers:` index", never "its source
+   * maps to a cache path". Those differ the moment the cache is warm:
+   * `LocalManifestCacheSource` serves a hit as a `file://` URL into
+   * `.telo/manifests/`, which no transport claims, so deriving the directory from
+   * `source` yields nothing and every OCI module would silently lose its artifact
+   * on the second and every later run — taking lazy asset materialization with it.
+   * The **pinned** `requestedUrl` survives a cache hit, so placement is derived
+   * from that, with a local `source` resolving to its own directory.
+   */
+  private buildModuleArtifacts(graph: LoadedGraph, manifestsDir: string | undefined): void {
+    this.moduleArtifacts.clear();
+    const transports = defaultTransportRegistry(this.registryUrl);
+    const entryDir = this._entryUrl ? resolveEntryDir(this._entryUrl) ?? "" : "";
+    for (const [, module] of graph.modules) {
+      const file = module.owner;
+      if (this.moduleArtifacts.has(file.source)) continue;
+      const artifact = moduleArtifactFor({
+        pinnedRef: file.requestedUrl,
+        layers: readOwnerManifest(file.text).layers,
+        moduleDir: moduleDirectoryFor(
+          file.requestedUrl,
+          file.source,
+          entryDir,
+          this.registryUrl,
+          manifestsDir,
+        ),
+        transports,
+        log: this.logging.kernelLogger(),
+      });
+      if (artifact) this.moduleArtifacts.set(file.source, artifact);
+    }
+  }
+
+  /** The artifact of the module whose manifest resolved from `source`, or
+   *  `undefined` for a module with no fetchable payload (already on disk,
+   *  manifest-only, or not cacheable). */
+  getModuleArtifact(source: string | undefined): ModuleArtifact | undefined {
+    return source ? this.moduleArtifacts.get(source) : undefined;
+  }
+
   /** Authored `kind` of a declared resource by name, from the static manifest
    *  set. Init-order-independent (unlike `resourceInstances`), so a controller
    *  resolving a `!ref <name>` sentinel before the target initializes can still

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

@@ -133,7 +133,7 @@ export class LocalManifestCacheSource implements ManifestSource {
 export function cachePathForCanonical(
   canonicalSource: string,
   entryDir: string,
-  registryUrl: string,
+  registryUrl: string | undefined = DEFAULT_REGISTRY_URL,
   manifestsDir?: string,
 ): string | null {
   const cacheRoot = manifestsDir ?? path.join(entryDir, CACHE_SUBDIR);

package/src/resource-context.ts

@@ -20,6 +20,9 @@ import {
   type TypeRule,
 } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
+import * as path from "path";
+import { pathToFileURL } from "url";
+import type { ModuleArtifact } from "./bundle/module-artifact.js";
 import { hostEnv } from "./host-env.js";
 import type { LoggingHost } from "./logging/logging-host.js";
 import type { ScopeConfig } from "./logging/scope-config.js";
@@ -326,7 +329,27 @@ export class ResourceContextImpl implements ResourceContext {
     describe: () => string,
     expects?: string,
   ): T {
-    return resolveRefInstance(value, this, guard, describe, expects);
+    // Two things the raw resolver cannot do from a `{ moduleContext }` slice:
+    //
+    //  - A `!ref` can reach a controller as the raw SENTINEL. Phase-5 injection is
+    //    field-map-driven, and the field map does not descend into the inline
+    //    declarations inside an `x-telo-scope` array, so a ref slot on a scoped
+    //    resource is not an injection site. (Phase 2.5 does rewrite such a
+    //    sentinel to `{kind, name}` when it can name a target, so the shape that
+    //    arrives varies — both are accepted.) `ensureKindRef` is the same rescue
+    //    the sentinel path already performs for hidden slots.
+    //  - A scope-local name lives in the OWNING context, not the module, so a
+    //    `with:`-scoped resource referencing a scoped sibling has to resolve in
+    //    the same order `contextForName` and `ScopeContext.getInstance` use —
+    //    scope-local first, module as the fallback — or CEL and `!ref` disagree
+    //    about what a name means inside a scope.
+    const normalized = isRefSentinel(value) ? this.ensureKindRef(value) : value;
+    return resolveRefInstance(normalized, this, guard, describe, expects);
+  }
+
+  /** Name lookup with scope-local precedence, for {@link resolveRefInstance}. */
+  resolveLocalInstance(name: string): ResourceInstance | undefined {
+    return this.contextForName(name).resourceInstances.get(name)?.instance;
   }
 
   async run(name: string) {
@@ -553,6 +576,60 @@ export class ResourceContextImpl implements ResourceContext {
     return this.kernel.getInstallRoot();
   }
 
+  /** The artifact of the module whose manifest resolved from `source`. Kernel-only
+   *  (it hands back a kernel class), reached by the resource-definition controller
+   *  through {@link ModuleArtifactHost} rather than the SDK surface. */
+  getModuleArtifact(source: string | undefined): ModuleArtifact | undefined {
+    return this.kernel.getModuleArtifact(source);
+  }
+
+  /**
+   * Resolve a module-relative reference against the declaring module's own
+   * directory, materializing the layers that could carry it on first use.
+   *
+   * A URI, not a filesystem path: the SDK is cross-runtime, and a path is only
+   * what *this* kernel happens to return for a module whose files are local.
+   * An already-absolute URI (one with a scheme) passes through untouched; a bare
+   * absolute filesystem path is returned as a `file://` URI rather than being
+   * rebased onto the module directory.
+   */
+  async resolveModuleFile(relative: string): Promise<string> {
+    // An absolute URI names its own location; a bare absolute path is already
+    // resolved and must not be rebased onto the module directory.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(relative)) return relative;
+    if (path.isAbsolute(relative)) return pathToFileURL(relative).href;
+
+    const source = this.moduleContext.source;
+    const artifact = this.kernel.getModuleArtifact(source);
+    if (artifact) {
+      // Both the `assets` layer and `common` — the sink rule puts a file the
+      // author did not claim via `assets:` into `common`, and a module that ships
+      // static files with no bundled controller has no other route to its payload.
+      // Fetching only assets would leave such a module resolving into an empty
+      // directory.
+      await artifact.materializeModuleFiles();
+      return new URL(relative, pathToFileURL(path.join(artifact.directory, "/")).href).href;
+    }
+    // No artifact means no payload to fetch. That is normal for a module already
+    // on disk (development) or one that ships no files — but for a module reached
+    // over a non-local scheme it means the artifact carries no layer index, i.e. it
+    // predates layers. Raise the actionable error here rather than leaving each
+    // caller to invent its own message from a URI it cannot open.
+    if (!source.startsWith("file://") && !path.isAbsolute(source)) {
+      throw new RuntimeError(
+        "ERR_MODULE_FILES_UNAVAILABLE",
+        `Cannot resolve '${relative}' against module '${source}': the module's artifact ` +
+          `carries no layer index, so its files cannot be located. It was published by an ` +
+          `older Telo that wrote a single-blob artifact — republish the module, or import it ` +
+          `from a local path during development.`,
+      );
+    }
+    // Local module: resolve against the manifest URL, the same rule `include:`
+    // and sibling imports follow.
+    const base = source.startsWith("file://") ? source : pathToFileURL(source).href;
+    return new URL(relative, base).href;
+  }
+
   on(event: string, handler: (payload?: any) => void | Promise<void>): void {
     this.kernel.on(event, handler);
   }

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

@@ -4,7 +4,34 @@ import { createHash } from "node:crypto";
 import { assertPublicEgress } from "../egress-guard.js";
 import { resolveDockerCredential } from "./docker-credentials.js";
 
-export const TELO_LAYER_MEDIA_TYPE = "application/vnd.telo.module.v1+tar";
+/** The **manifest layer**: the blob carrying `telo.yaml`. The only layer located
+ *  through the OCI manifest — its bytes are then verified against the import
+ *  pin, and every other layer is addressed by a digest the pinned `layers:` index
+ *  supplies. */
+export const TELO_MANIFEST_LAYER_MEDIA_TYPE = "application/vnd.telo.module.manifest.v1+tar";
+
+/**
+ * The pre-layers single-blob artifact: `telo.yaml` and the whole `files:` payload
+ * in one layer.
+ *
+ * Still read, because every module published so far carries it and the ones with
+ * no payload — the npm-backed majority — are perfectly usable from it: the read
+ * path only ever wanted `telo.yaml`, and this blob contains it. What such an
+ * artifact cannot supply is a `layers:` index, so a module that *does* ship a
+ * payload resolves its manifest and then fails at the controller with an
+ * actionable "republish" error. That is the intended, narrow break.
+ */
+export const TELO_LEGACY_LAYER_MEDIA_TYPE = "application/vnd.telo.module.v1+tar";
+
+/** A **payload layer**: one controller selector's files, the `assets` layer, or
+ *  the `common` layer. Which is which is read from the pinned index, never from
+ *  the descriptor — the annotations below are for `docker manifest inspect`
+ *  legibility only and are never read back. */
+export const TELO_PAYLOAD_LAYER_MEDIA_TYPE = "application/vnd.telo.module.layer.v1+tar";
+
+export const TELO_LAYER_ROLE_ANNOTATION = "run.telo.layer.role";
+export const TELO_LAYER_SELECTOR_ANNOTATION = "run.telo.layer.selector";
+
 export const OCI_MANIFEST_MEDIA_TYPE = "application/vnd.oci.image.manifest.v1+json";
 export const OCI_EMPTY_CONFIG_MEDIA_TYPE = "application/vnd.oci.empty.v1+json";
 
@@ -25,6 +52,10 @@ export interface OciDescriptor {
   size: number;
   data?: string;
   artifactType?: string;
+  /** Descriptive per-layer metadata (`run.telo.layer.*`). Written so native
+   *  tooling can read the artifact's shape; never consumed by Telo, which takes
+   *  role and selector from the pinned index instead. */
+  annotations?: Record<string, string>;
 }
 
 export interface OciManifest {

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

@@ -1,17 +1,23 @@
 import {
   DEFAULT_MANIFEST_FILENAME,
   IntegrityError,
+  selectorKey,
   sha256Base64Url,
   verifyIntegrity,
+  type ArtifactLayer,
   type ManifestCacheCoords,
   type ManifestSource,
 } from "@telorun/analyzer";
+import { createHash } from "node:crypto";
 
-import { computeFilesIntegrity, injectFilesIntegrity } from "../../bundle/files-integrity.js";
+import {
+  computeFilesIntegrity,
+  injectLayerIndex,
+  type PayloadFile,
+} from "../../bundle/files-integrity.js";
 import { readOwnerManifest, type OwnerManifest } from "../../bundle/module-manifest.js";
 import { makeTarGz, readTarGz, toPayloadFiles } from "../../bundle/tar.js";
 import type {
-  FetchedArtifact,
   PublishBundle,
   PublishOptions,
   PublishResult,
@@ -20,7 +26,12 @@ import type {
 import {
   OciClient,
   OCI_MANIFEST_MEDIA_TYPE,
-  TELO_LAYER_MEDIA_TYPE,
+  TELO_LAYER_ROLE_ANNOTATION,
+  TELO_LEGACY_LAYER_MEDIA_TYPE,
+  TELO_LAYER_SELECTOR_ANNOTATION,
+  TELO_MANIFEST_LAYER_MEDIA_TYPE,
+  TELO_PAYLOAD_LAYER_MEDIA_TYPE,
+  type OciDescriptor,
   type OciManifest,
 } from "./oci-client.js";
 import {
@@ -31,23 +42,44 @@ import {
   withRefVersion,
 } from "./oci-ref.js";
 
-/** Pull the module blob, returning its extracted entries and the `telo.yaml`
- *  bytes, verified against the ref's inline hash and its own `filesIntegrity`. */
-async function pullVerified(ref: string): Promise<FetchedArtifact> {
+/**
+ * Pull only the **manifest layer** and return its verified `telo.yaml` text.
+ *
+ * This is the one place the OCI manifest is load-bearing: it is fetched by a
+ * reference that is usually a mutable tag and Telo never hashes it, so it is used
+ * solely to locate the blob carrying `telo.yaml`. Those bytes are then checked
+ * against the import's inline pin, which is what makes the rest of the artifact
+ * safe to address from the `layers:` index inside them — tampering with the OCI
+ * manifest can only change *which* blob is offered as the manifest, and a
+ * substituted one fails the pin here.
+ *
+ * Payload layers are never pulled on this path, so reading a manifest no longer
+ * downloads a payload it discards.
+ *
+ * A pre-layers single-blob artifact is still read here: it contains `telo.yaml`
+ * too, which is all this path wants, so every already-published module keeps
+ * resolving. What it cannot offer is a `layers:` index — so a module that ships a
+ * 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);
   const manifest = await client.pullManifest(reference);
   const layer =
-    manifest.layers.find((l) => l.mediaType === TELO_LAYER_MEDIA_TYPE) ?? manifest.layers[0];
+    manifest.layers.find((l) => l.mediaType === TELO_MANIFEST_LAYER_MEDIA_TYPE) ??
+    manifest.layers.find((l) => l.mediaType === TELO_LEGACY_LAYER_MEDIA_TYPE) ??
+    manifest.layers[0];
   if (!layer) {
     throw new Error(`OCI artifact ${ref} has no layers`);
   }
-  const tar = await client.pullBlob(layer.digest);
-  const entries = await readTarGz(tar);
+  const entries = await readTarGz(await client.pullBlob(layer.digest));
 
   const teloEntry = entries.find((e) => e.name === DEFAULT_MANIFEST_FILENAME);
   if (!teloEntry) {
-    throw new Error(`OCI artifact ${ref} blob does not contain ${DEFAULT_MANIFEST_FILENAME}`);
+    throw new Error(
+      `OCI artifact ${ref} manifest layer does not contain ${DEFAULT_MANIFEST_FILENAME}`,
+    );
   }
   const manifestText =
     typeof teloEntry.content === "string" ? teloEntry.content : teloEntry.content.toString("utf-8");
@@ -56,28 +88,18 @@ async function pullVerified(ref: string): Promise<FetchedArtifact> {
   if (integrity) {
     await verifyIntegrity(new TextEncoder().encode(manifestText), integrity, ref);
   }
-
-  const files = toPayloadFiles(entries);
-
-  const { filesIntegrity } = readOwnerManifest(manifestText);
-  if (filesIntegrity) {
-    const actual = await computeFilesIntegrity(files);
-    if (actual !== filesIntegrity) {
-      throw new IntegrityError(
-        `Integrity check failed for ${ref}: filesIntegrity expected ${filesIntegrity}, ` +
-          `got ${actual}. The payload does not match the recorded hash.`,
-      );
-    }
-  }
-
-  return { manifest: manifestText, files };
+  return manifestText;
 }
 
 /**
  * OCI transport: `oci://host/repo@reference` modules on any OCI distribution
  * registry (GHCR / ECR / Docker Hub / Harbor), over a hand-rolled minimal
- * client. A module is a single artifact — one tar blob carrying `telo.yaml`
- * and the `files:` payload — pushed under a standard OCI artifact manifest.
+ * client. A module is one OCI artifact whose layers are the module's layers —
+ * `telo.yaml` in its own blob, then one blob per controller selector, plus the
+ * `assets` and `common` blobs — so a client fetches only what it needs. A flat
+ * layer list, not an image index: the manifest and asset layers are
+ * platform-neutral, so a manifest list would duplicate them per platform entry
+ * and add a round trip for a selection made from the pinned index anyway.
  *
  * Not browser-reachable (token handshake, Docker credentials, tar extraction),
  * so its resolution `source` is Node-only; the editor resolves `oci://` imports
@@ -90,7 +112,7 @@ export class OciTransport implements Transport {
     this.source = {
       supports: (url) => this.supports(url),
       read: async (url) => {
-        const { manifest } = await pullVerified(url);
+        const manifest = await pullManifestLayer(url);
         const { host, repo, reference } = parseOciRef(url);
         return { text: manifest, source: `${OCI_SCHEME}${host}/${repo}@${reference}` };
       },
@@ -159,24 +181,38 @@ export class OciTransport implements Transport {
     return new OciClient(host, repo).headManifest(reference);
   }
 
-  async fetchArtifact(ref: string): Promise<FetchedArtifact> {
-    return pullVerified(ref);
+  /** Pull one payload layer by the `blob` digest the pinned index supplies. The
+   *  OCI layer list is not consulted — a digest addresses a blob directly, so a
+   *  republish that reorders layers is simply invisible here rather than a
+   *  failure. Content verification is the artifact handle's, which holds the
+   *  expected `integrity`. */
+  async fetchLayer(ref: string, blobDigest: string): Promise<PayloadFile[]> {
+    const { host, repo } = parseOciRef(ref);
+    const tar = await new OciClient(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
+    // covers the file set, not the archive that carried it.
+    const actual = `sha256:${createHash("sha256").update(tar).digest("hex")}`;
+    if (actual !== blobDigest) {
+      throw new IntegrityError(
+        `Blob digest mismatch fetching a layer of ${ref}: requested ${blobDigest}, ` +
+          `received ${actual}. The registry returned different bytes than were addressed.`,
+      );
+    }
+    return toPayloadFiles(await readTarGz(tar));
   }
 
   /** Hashes the **UTF-8 encoding of the extracted `telo.yaml`**, which is what
-   *  `pullVerified` checks an inline `#sha256-…` pin against on the read path.
+   *  `pullManifestLayer` 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. */
+   *  Deliberately uncached — a pin must hash what is published *now*, not a
+   *  cached copy — but since `telo.yaml` is its own layer this costs one small
+   *  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 pullVerified(ref);
+    const manifest = await pullManifestLayer(ref);
     return `sha256-${await sha256Base64Url(new TextEncoder().encode(manifest))}`;
   }
 
@@ -221,27 +257,62 @@ export class OciTransport implements Transport {
       );
     }
     const tag = identity.version;
+    const client = new OciClient(host, repo);
 
-    // Pin the payload, then pack telo.yaml + files into the single module blob.
-    let manifestText = bundle.manifest;
-    if (bundle.files.length > 0) {
-      manifestText = injectFilesIntegrity(manifestText, await computeFilesIntegrity(bundle.files));
+    // Push every payload layer first, collecting the digests that address them.
+    // This ordering is what keeps the index non-circular: the manifest layer is
+    // pushed last and names only the layers pushed before it, never itself.
+    const payloadDescriptors: OciDescriptor[] = [];
+    const index: ArtifactLayer[] = [];
+    for (const layer of bundle.layers) {
+      if (layer.files.length === 0) continue;
+      const tar = await makeTarGz(
+        layer.files.map((f) => ({ name: f.name, content: Buffer.from(f.content) })),
+      );
+      const blob = await client.pushBlob(tar);
+      payloadDescriptors.push({
+        mediaType: TELO_PAYLOAD_LAYER_MEDIA_TYPE,
+        digest: blob,
+        size: tar.length,
+        annotations: {
+          [TELO_LAYER_ROLE_ANNOTATION]: layer.role,
+          ...(layer.selector
+            ? { [TELO_LAYER_SELECTOR_ANNOTATION]: selectorKey(layer.selector) }
+            : {}),
+        },
+      });
+      index.push({
+        role: layer.role,
+        ...(layer.selector ? { selector: layer.selector } : {}),
+        blob,
+        integrity: await computeFilesIntegrity(layer.files),
+      });
     }
-    const tar = await makeTarGz([
+
+    // Inject the index, then push telo.yaml as its own layer so a manifest read
+    // never has to pull a payload.
+    const manifestText =
+      index.length > 0 ? injectLayerIndex(bundle.manifest, index) : bundle.manifest;
+    const manifestTar = await makeTarGz([
       { name: DEFAULT_MANIFEST_FILENAME, content: manifestText },
-      ...bundle.files.map((f) => ({ name: f.name, content: Buffer.from(f.content) })),
     ]);
+    const manifestBlob = await client.pushBlob(manifestTar);
 
-    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,
+      artifactType: TELO_MANIFEST_LAYER_MEDIA_TYPE,
       config,
-      layers: [{ mediaType: TELO_LAYER_MEDIA_TYPE, digest: layerDigest, size: tar.length }],
+      layers: [
+        {
+          mediaType: TELO_MANIFEST_LAYER_MEDIA_TYPE,
+          digest: manifestBlob,
+          size: manifestTar.length,
+        },
+        ...payloadDescriptors,
+      ],
       ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
     };
     await client.pushManifest(tag, manifest);

package/src/transports/registry-transport.ts

@@ -1,7 +1,6 @@
 import {
   DEFAULT_MANIFEST_FILENAME,
   HttpSource,
-  IntegrityError,
   RegistrySource,
   isRegistryRef,
   parseModuleRef,
@@ -15,12 +14,9 @@ import {
 import { fetchOrThrow } from "@telorun/sdk";
 import { createHash } from "crypto";
 
-import { computeFilesIntegrity } from "../bundle/files-integrity.js";
-import { readOwnerManifest } from "../bundle/module-manifest.js";
-import { readTarGz, toPayloadFiles } from "../bundle/tar.js";
+import type { PayloadFile } from "../bundle/files-integrity.js";
 import { assertPublicEgress } from "./egress-guard.js";
 import type {
-  FetchedArtifact,
   PublishBundle,
   PublishOptions,
   PublishResult,
@@ -272,39 +268,15 @@ export class RegistryTransport implements Transport {
     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);
-    const meta = readOwnerManifest(manifest);
-    if (!meta.declaresFiles) return { manifest, files: [] };
-
-    // 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 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}`);
-    }
-    const files = toPayloadFiles(await readTarGz(Buffer.from(await res.arrayBuffer())));
-
-    // Verify the payload against the manifest's `filesIntegrity` before handing
-    // it back — a mismatch is terminal (a tampered bundle must never be used).
-    // The manifest that carries the hash is itself pinned by the inline hash.
-    if (meta.filesIntegrity) {
-      const actual = await computeFilesIntegrity(files);
-      if (actual !== meta.filesIntegrity) {
-        throw new IntegrityError(
-          `Integrity check failed for bundle ${tarUrl}: filesIntegrity expected ` +
-            `${meta.filesIntegrity}, got ${actual}. The payload does not match the recorded ` +
-            `hash — the module may have been tampered with or republished.`,
-        );
-      }
-    }
-
-    return { manifest, files };
+  /** Layered artifacts are an OCI concept, and the registry origin is read-only
+   *  — nothing has ever published a payload here, so there is no layer to pull.
+   *  A module reached over the registry is manifest-only, and its controllers
+   *  come from npm. */
+  async fetchLayer(ref: string, blobDigest: string): Promise<PayloadFile[]> {
+    throw new Error(
+      `Cannot fetch layer ${blobDigest} of ${ref}: the Telo registry serves manifests only. ` +
+        `A module with a bundled payload is published as an OCI artifact (oci://host/repo).`,
+    );
   }
 
   async publish(

package/src/transports/transport-registry.ts

@@ -1,9 +1,9 @@
 import type { ManifestCacheCoords, ManifestSource } from "@telorun/analyzer";
 
+import type { PayloadFile } from "../bundle/files-integrity.js";
 import { OciTransport } from "./oci/oci-transport.js";
 import { RegistryTransport } from "./registry-transport.js";
 import type {
-  FetchedArtifact,
   PublishBundle,
   PublishOptions,
   PublishResult,
@@ -41,10 +41,10 @@ export class TransportRegistry {
     return this.require(ref).listVersions(ref);
   }
 
-  /** Full artifact for `ref` via its owning transport. Throws when no transport
-   *  owns the ref. */
-  fetchArtifact(ref: string): Promise<FetchedArtifact> {
-    return this.require(ref).fetchArtifact(ref);
+  /** One payload layer of `ref`, addressed by the `blob` digest its pinned index
+   *  entry carries. Throws when no transport owns the ref. */
+  fetchLayer(ref: string, blobDigest: string): Promise<PayloadFile[]> {
+    return this.require(ref).fetchLayer(ref, blobDigest);
   }
 
   /** Cheap content-identity digest for `ref` via its owning transport; `null`