@telorun/kernel 0.61.0 → 0.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -61,9 +61,9 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.6.1",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.49.0",
+    "@telorun/analyzer": "0.49.1",
     "@telorun/glob": "0.2.0",
-    "@telorun/templating": "0.11.0",
+    "@telorun/templating": "0.11.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "packageurl-js": "^2.0.1",
@@ -75,7 +75,7 @@
     "@types/tar-stream": "^3.1.3",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.61.0"
+    "@telorun/sdk": "0.62.0"
   },
   "optionalDependencies": {
     "esbuild": "^0.28.1"

package/src/bundle/module-artifact.ts

@@ -26,6 +26,17 @@ export interface MaterializedLayer {
   files: string[];
 }
 
+/** A materialized controller layer plus whether reaching it cost a transfer.
+ *
+ *  `transferred` is out of band rather than a field on `MaterializedLayer`
+ *  because it describes THIS call, not the layer: the value is memoized and
+ *  shared, so a flag on it would be meaningless to every other caller. Only the
+ *  controller path reports progress, so only it asks. */
+export interface ResolvedControllerLayer {
+  layer: MaterializedLayer;
+  transferred: boolean;
+}
+
 /**
  * Map Node's platform vocabulary onto the canonical OCI/GOOS names selectors are
  * published with. Node says `win32`/`x64`; OCI descriptors say
@@ -123,8 +134,11 @@ export class ModuleArtifact {
   private readonly transports: TransportRegistry;
   private readonly log: Logger;
   /** In-flight / completed materializations, keyed by blob digest. Rejections
-   *  are dropped so a transient fetch failure retries on the next ask. */
-  private readonly inFlight = new Map<string, Promise<MaterializedLayer>>();
+   *  are dropped so a transient fetch failure retries on the next ask. Each
+   *  records whether the work it wraps transferred the layer or read it off
+   *  disk — the memoized entry is shared, so a joining caller reads the flag
+   *  but never claims it. */
+  private readonly inFlight = new Map<string, Promise<ResolvedControllerLayer>>();
 
   constructor(opts: {
     pinnedRef: string;
@@ -165,14 +179,23 @@ export class ModuleArtifact {
    * Returns `undefined` when the artifact ships no layer for this selector, which
    * is how a loader learns to fall through to the next candidate.
    */
-  async materializeController(selector: ArtifactSelector): Promise<MaterializedLayer | undefined> {
+  async materializeController(
+    selector: ArtifactSelector,
+  ): Promise<ResolvedControllerLayer | undefined> {
     const key = selectorKey(selector);
     const layer = this.layers.find(
       (l) => l.role === "controller" && l.selector !== undefined && selectorKey(l.selector) === key,
     );
     if (!layer) return undefined;
-    await this.materializeCommon();
-    return this.materialize(layer);
+    const common = await this.materializeCommonTracked();
+    const controller = await this.materializeTracked(layer);
+    // Either half is a transfer the caller waited on: the common layer's bytes
+    // come down on this call too, so they are as much of a wait as the
+    // controller layer's.
+    return {
+      layer: controller.layer,
+      transferred: controller.transferred || (common?.transferred ?? false),
+    };
   }
 
   /**
@@ -197,8 +220,15 @@ export class ModuleArtifact {
 
   /** Materialize the `common` layer, if the module ships one. */
   async materializeCommon(): Promise<MaterializedLayer | undefined> {
+    return (await this.materializeCommonTracked())?.layer;
+  }
+
+  /** As `materializeCommon`, reporting whether this call transferred it — the
+   *  controller path rides the common layer along and has to count its bytes as
+   *  part of the wait. One lookup, so "common comes too" is encoded once. */
+  private async materializeCommonTracked(): Promise<ResolvedControllerLayer | undefined> {
     const layer = singletonLayer(this.layers, "common");
-    return layer ? this.materialize(layer) : undefined;
+    return layer ? this.materializeTracked(layer) : undefined;
   }
 
   /**
@@ -226,9 +256,21 @@ export class ModuleArtifact {
       .join(", ");
   }
 
-  private materialize(layer: ArtifactLayer): Promise<MaterializedLayer> {
+  private async materialize(layer: ArtifactLayer): Promise<MaterializedLayer> {
+    return (await this.materializeTracked(layer)).layer;
+  }
+
+  /**
+   * As `materialize`, but also reporting whether THIS call transferred the layer.
+   *
+   * A caller that joins work already in flight reports `false`: several
+   * controller candidates of one module share a layer, and attributing the
+   * transfer to all of them would print one progress line per candidate for a
+   * single download. The call that started the work owns the report.
+   */
+  private materializeTracked(layer: ArtifactLayer): Promise<ResolvedControllerLayer> {
     const pending = this.inFlight.get(layer.blob);
-    if (pending) return pending;
+    if (pending) return pending.then((r) => ({ layer: r.layer, transferred: false }));
     const work = this.materializeUncached(layer).catch((err) => {
       // Drop the rejection so a transient fetch failure is retried rather than
       // cached for the lifetime of the module.
@@ -247,10 +289,10 @@ export class ModuleArtifact {
     return path.join(this.dir, `.telo-layer-${layer.role}-${short}`);
   }
 
-  private async materializeUncached(layer: ArtifactLayer): Promise<MaterializedLayer> {
+  private async materializeUncached(layer: ArtifactLayer): Promise<ResolvedControllerLayer> {
     const marker = this.markerPath(layer);
     if (existsSync(marker)) {
-      return { dir: this.dir, files: await readMarker(marker) };
+      return { layer: { dir: this.dir, files: await readMarker(marker) }, transferred: false };
     }
 
     return withDirectoryLock(
@@ -260,7 +302,7 @@ export class ModuleArtifact {
         // Re-check inside the lock: a peer may have extracted this layer between
         // the fast-path miss and our acquisition.
         if (existsSync(marker)) {
-          return { dir: this.dir, files: await readMarker(marker) };
+          return { layer: { dir: this.dir, files: await readMarker(marker) }, transferred: false };
         }
 
         const files = await this.transports.fetchLayer(this.pinnedRef, layer.blob);
@@ -283,7 +325,7 @@ export class ModuleArtifact {
           "telo.layer.role": layer.role,
           "telo.layer.files": written.length,
         });
-        return { dir: this.dir, files: written };
+        return { layer: { dir: this.dir, files: written }, transferred: true };
       },
       this.log,
     );

package/src/controller-loader.ts

@@ -8,10 +8,13 @@ import { ControllerPolicy, DEFAULT_POLICY, POLICY_WILDCARD } from "./runtime-reg
 export type { ControllerPolicy } from "./runtime-registry.js";
 
 /**
- * Which branch the per-scheme loader actually took. Cache/local hits resolve
- * in milliseconds; `npm-install` and `cargo-build` are the only branches that
- * do real (network or compile) work. The CLI uses this to decide whether a
- * "downloading…" line was honest or should be erased.
+ * Which branch the per-scheme loader actually took. Cache/local hits resolve in
+ * milliseconds; `npm-install`, `cargo-build` and `bundle` are the branches that
+ * do real (network or compile) work — `bundle` is reported only when the resolve
+ * fetched the module's controller layer, never when it found it already
+ * extracted. The CLI uses this to decide whether a "downloading…" line was
+ * honest or should be erased, so a source that names work no one waited for
+ * turns every warm start into noise.
  */
 export type ControllerResolveSource =
   | "local"

package/src/controller-loaders/bundle-loader.ts

@@ -220,17 +220,22 @@ export class BundleControllerLoader {
     // fetched here: the artifact handle owns the pinned ref and the verified
     // layer index, so an `oci://` module ref never reaches this loader as a path.
     let bundleDir: string;
+    // What this resolve actually cost. A module already on disk is `local`; an
+    // artifact layer found extracted is `cache`; only a layer this call pulled
+    // down reports `bundle`, the branch that made the user wait.
+    let source: ControllerResolveSource = "local";
     if (artifact) {
       // By its own selector, not by re-matching the host: this candidate IS one
       // selector, and it is exactly the key of the layer that carries it.
-      const layer = await artifact.materializeController(selector);
-      if (!layer) {
+      const resolved = await artifact.materializeController(selector);
+      if (!resolved) {
         throw new ControllerEnvMissingError(
           `pkg:telo controller "${purl}": the module artifact ships no layer for ` +
             `${describeSelector(selector)} (has: ${artifact.describeLayers()})`,
         );
       }
-      bundleDir = layer.dir;
+      bundleDir = resolved.layer.dir;
+      source = resolved.transferred ? "bundle" : "cache";
     } else {
       // No artifact: a module already on disk (local development, or a manifest
       // served from the on-disk cache). Its files sit next to the manifest.
@@ -258,7 +263,7 @@ export class BundleControllerLoader {
 
     const fragment = parsed.subpath;
     return {
-      source: "bundle",
+      source,
       importInstance: async () => {
         // A broken bundle (syntax / failed import) is a real user-code failure —
         // let it propagate rather than masking it as env-missing.

package/src/controller-loaders/npm-loader.ts

@@ -149,7 +149,7 @@ export class NpmControllerLoader {
    * same spec share one `npm install <spec>` invocation rather than each
    * acquiring the fs-lock and reinstalling.
    */
-  private readonly inFlight = new Map<string, Promise<void>>();
+  private readonly inFlight = new Map<string, Promise<boolean>>();
 
   /**
    * Promise that resolves when the install root has been materialized
@@ -264,15 +264,20 @@ export class NpmControllerLoader {
       dependencies[name] = `file:${resolvedPkgRoot}`;
     }
 
-    const packageJson = {
-      name: "telo-runtime-install",
-      private: true,
-      version: "0.0.0",
-      dependencies,
-    };
     const packageJsonPath = path.join(installRoot, "package.json");
     const stateFile = path.join(installRoot, ".telo-state.json");
-    const newHash = sha256(JSON.stringify(packageJson));
+    // Keyed on the realm deps alone — the only part this function owns. The
+    // controller aliases below join the file but never the identity: they are
+    // added one `--save` at a time, so hashing them would make every controller
+    // install invalidate the root and trigger another root install.
+    const newHash = sha256(
+      JSON.stringify({
+        name: "telo-runtime-install",
+        private: true,
+        version: "0.0.0",
+        dependencies,
+      }),
+    );
 
     await fs.mkdir(installRoot, { recursive: true });
 
@@ -301,7 +306,25 @@ export class NpmControllerLoader {
         return;
       }
 
-      await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+      // Rewrite the root's package.json REALM DEPS ONLY, keeping every
+      // controller alias a previous `installPackage --save` recorded. Writing a
+      // fresh file instead drops them, and the install below then prunes their
+      // `node_modules` folders — so a realm change (a different kernel checkout,
+      // e.g. a globally installed CLI and a repo one addressing the same app)
+      // evicted every controller and reinstalled the lot, on every switch.
+      const existingDeps = (await readPackageDeps(installRoot)) ?? {};
+      const merged: Record<string, string> = {
+        ...(await liveControllerDeps(existingDeps, installRoot)),
+        ...dependencies,
+      };
+      await fs.writeFile(
+        packageJsonPath,
+        JSON.stringify(
+          { name: "telo-runtime-install", private: true, version: "0.0.0", dependencies: merged },
+          null,
+          2,
+        ) + "\n",
+      );
       await runPackageManager(installRoot, [
         "install",
         "--no-audit",
@@ -414,8 +437,11 @@ export class NpmControllerLoader {
       }
     }
 
+    // Resolves to whether the package manager actually ran: the re-check below
+    // routinely wins the race, and reporting an install that never happened
+    // makes the CLI print a "downloading…" line nobody waited for.
     const work = (async () => {
-      await withDirectoryLock(installRoot, "controller install", async () => {
+      return withDirectoryLock(installRoot, "controller install", async () => {
         // Re-check inside the lock: a peer process may have installed the
         // spec between the fast-path miss and our acquisition.
         if (kind === "registry") {
@@ -424,7 +450,7 @@ export class NpmControllerLoader {
             installedVersion !== null &&
             (requestedVersion === null || requestedVersion === installedVersion)
           ) {
-            return;
+            return false;
           }
         } else {
           // Normalize the on-disk record to absolute form before comparing —
@@ -436,7 +462,7 @@ export class NpmControllerLoader {
             (await pathExists(targetPath))
           ) {
             this.rootDeps[alias] = lockedSpec;
-            return;
+            return false;
           }
         }
 
@@ -458,16 +484,21 @@ export class NpmControllerLoader {
         const written = await readDepSpec(installRoot, alias);
         if (written !== undefined) this.rootDeps[alias] = written;
         else this.rootDeps[alias] = spec;
+        return true;
       }, this.log);
     })();
 
     this.inFlight.set(cacheKey, work);
+    let installed: boolean;
     try {
-      await work;
+      installed = await work;
     } finally {
       this.inFlight.delete(cacheKey);
     }
     this.installedSpecs.add(cacheKey);
+    // A peer that won the lock had already put the package there, so nothing
+    // was installed — that is a cache hit, whatever the fast path thought.
+    if (!installed) return "cache";
     // First-touch local installs report `local` (silenced in CLI progress);
     // fresh registry installs report `npm-install` (the only branch a
     // user-facing "downloading…" line should ever surface for).
@@ -693,6 +724,37 @@ function normalizeFileSpec(spec: string, installRoot: string): string {
  * Returns null when the file is missing or unreadable; callers decide whether
  * to seed from a synthesized map instead.
  */
+/**
+ * The subset of a root's recorded dependencies still worth carrying into a
+ * rewrite: the package manager has to resolve every entry, so one dead record
+ * fails the whole install.
+ *
+ * Dropped: a `file:` spec whose target no longer exists (the app was run from a
+ * checkout that has since moved, or the app directory was copied without it),
+ * and an alias with no folder in `node_modules`. Both are free to drop —
+ * `installPackage` reinstalls a controller the moment something asks for it —
+ * and keeping them is not: a dangling `file:` dep makes the root install fail
+ * with an ENOENT that names nothing in the manifest, and since the state file is
+ * only written after a successful install, every later run repeats it. This is
+ * also what stops aliases accumulating forever now that the rewrite preserves
+ * them: a version an app has moved off drops out on the next root install.
+ */
+async function liveControllerDeps(
+  deps: Record<string, string>,
+  installRoot: string,
+): Promise<Record<string, string>> {
+  const live: Record<string, string> = {};
+  for (const [name, spec] of Object.entries(deps)) {
+    if (spec.startsWith("file:")) {
+      const target = normalizeFileSpec(spec, installRoot).slice("file:".length);
+      if (!(await pathExists(target))) continue;
+    }
+    if (!(await pathExists(path.join(installRoot, "node_modules", name)))) continue;
+    live[name] = spec;
+  }
+  return live;
+}
+
 async function readPackageDeps(installRoot: string): Promise<Record<string, string> | null> {
   try {
     const text = await fs.readFile(path.join(installRoot, "package.json"), "utf8");

package/src/index.ts

@@ -32,6 +32,7 @@ export {
   moduleDirectoryFor,
   hostPlatformTarget,
   type MaterializedLayer,
+  type ResolvedControllerLayer,
 } from "./bundle/module-artifact.js";
 export { readOwnerManifest, type OwnerManifest } from "./bundle/module-manifest.js";
 export type {
@@ -46,7 +47,7 @@ export { nodeCelHandlers } from "./cel-handlers.js";
 export { ModuleContext } from "./module-context.js";
 export { ManifestRegistry as Registry } from "./registry.js";
 export { ResourceURI } from "./resource-uri.js";
-export type { RuntimeDiagnostic } from "@telorun/sdk";
+export type { DiagnosticOrigin, RuntimeDiagnostic } from "@telorun/sdk";
 export { describeBlockedGroup, groupBlockedResources } from "./init-failure-diagnostics.js";
 
 // Structured logging — the runtime half of kernel/specs/logging.md. The record

package/src/kernel.ts

@@ -74,6 +74,7 @@ import {
 } from "./application-env.js";
 import { policyFingerprint } from "./runtime-registry.js";
 import { SchemaValidator } from "./schema-validator.js";
+import { staticDiagnosticToRuntime } from "./static-analysis-diagnostics.js";
 
 /** Walks up the EvaluationContext parent chain to the nearest enclosing
  *  ModuleContext and returns its controller policy (or undefined). Used to
@@ -435,20 +436,27 @@ export class Kernel implements IKernel {
     if (analysisGraph.errors.length > 0) {
       throw analysisGraph.errors[0].error;
     }
+    // Recorded before the first throw below: the graph is what a renderer
+    // resolves a static failure's `origin` against, and a parse error is
+    // exactly the failure that most needs to name a line.
+    this._loadedGraph = analysisGraph;
     // A YAML parse failure yields a mangled manifest tree — fatal before any
     // controller sees it, and more fundamental than a version conflict.
     if (analysisGraph.parseDiagnostics.length > 0) {
       throw new RuntimeError(
         "ERR_MANIFEST_VALIDATION_FAILED",
+        // The message keeps the whole failure for a consumer that only reads
+        // `error.message`; the diagnostics carry the same set structured, so a
+        // renderer can locate each one instead of re-parsing this text.
         analysisGraph.parseDiagnostics
           .map((d) => {
             const filePath = (d.data as { filePath?: string } | undefined)?.filePath;
             return filePath ? `${filePath}: ${d.message}` : d.message;
           })
           .join("\n"),
+        analysisGraph.parseDiagnostics.map(staticDiagnosticToRuntime),
       );
     }
-    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
@@ -460,6 +468,7 @@ export class Kernel implements IKernel {
       throw new RuntimeError(
         "ERR_MANIFEST_VALIDATION_FAILED",
         versionConflicts.map((d) => d.message).join("\n"),
+        versionConflicts.map(staticDiagnosticToRuntime),
       );
     }
     for (const d of analysisGraph.versionDiagnostics) {
@@ -512,14 +521,7 @@ export class Kernel implements IKernel {
       throw new RuntimeError(
         "ERR_MANIFEST_VALIDATION_FAILED",
         "Manifest validation failed",
-        errors.map((d) => ({
-          severity: "error" as const,
-          message: d.message,
-          code: d.code !== undefined ? String(d.code) : undefined,
-          resource: (d.data as any)?.resource
-            ? `${(d.data as any).resource.kind}.${(d.data as any).resource.name}`
-            : undefined,
-        })),
+        errors.map(staticDiagnosticToRuntime),
       );
     }
     if (manifestsDir && writeCache && !skipValidation) {
@@ -764,14 +766,7 @@ export class Kernel implements IKernel {
       throw new RuntimeError(
         "ERR_MANIFEST_VALIDATION_FAILED",
         "Manifest validation failed",
-        refErrors.map((d) => ({
-          severity: "error" as const,
-          message: d.message,
-          code: d.code !== undefined ? String(d.code) : undefined,
-          resource: (d.data as any)?.resource
-            ? `${(d.data as any).resource.kind}.${(d.data as any).resource.name}`
-            : undefined,
-        })),
+        refErrors.map(staticDiagnosticToRuntime),
       );
     }
     if (cycleError) {

package/src/static-analysis-diagnostics.ts

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

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

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

package/src/transports/transport-registry.ts

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