@telorun/kernel 0.59.0 → 0.61.0

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";
@@ -171,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();
 
@@ -573,6 +657,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/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/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(