@telorun/kernel 0.78.0 → 0.79.0

package/src/controller-loader.ts

@@ -39,10 +39,44 @@ export interface ResolvedController {
   purl: string;
   source: ControllerResolveSource;
   importInstance: () => Promise<ControllerInstance>;
+  /**
+   * How long the caller has waited for this controller, measured from the
+   * first {@link ControllerWorkKind} branch it entered — or, when it entered
+   * none, from the `importInstance()` call. Resolution is what installs,
+   * compiles and fetches, so timing only the import reports a 40-second
+   * install as a few milliseconds.
+   */
+  waitedMs: () => number;
 }
 
+/**
+ * A branch that makes the caller wait: a registry install, a compile, or a
+ * layer transfer. Reported by the sub-loader that is about to enter it, which
+ * is the only place that knows — a resolve's `source` is a verdict available
+ * only afterwards, and a warm start enters no branch at all, so nothing is
+ * announced for it. Reported for work in the resolve *and* the import phase:
+ * a dev-mode `pkg:telo` build and a `cargo build` are both paid inside
+ * `importInstance`.
+ */
+export type ControllerWorkKind = "npm-install" | "cargo-build" | "source-build" | "layer-fetch";
+
+/**
+ * Sub-loader hook, invoked immediately before entering a {@link
+ * ControllerWorkKind} branch. Awaited, so a consumer that renders progress has
+ * its line on screen before the wait starts rather than after it.
+ */
+export type ControllerWorkReporter = (work: ControllerWorkKind) => void | Promise<void>;
+
 export type ControllerLoaderEvent =
-  | { name: "ControllerLoading"; payload: { purl: string } }
+  /**
+   * A resolved controller is about to be imported. `source` names the branch
+   * the resolve took, so a consumer can tell a warm start (`cache` / `local`)
+   * from work someone waited for (`npm-install`, `cargo-build`, `bundle`)
+   * *before* rendering anything. The event is emitted after resolution
+   * precisely so this is known: resolution is what fetches, installs and
+   * builds, and an event emitted ahead of it could only speculate.
+   */
+  | { name: "ControllerLoading"; payload: { purl: string; source: ControllerResolveSource } }
   | {
       name: "ControllerLoaded";
       payload: { purl: string; source: ControllerResolveSource; durationMs: number };
@@ -55,7 +89,15 @@ export type ControllerLoaderEvent =
    * which is non-recoverable. Consumers that opened a UI element on the
    * matching `ControllerLoading` should close it out here.
    */
-  | { name: "ControllerLoadSkipped"; payload: { purl: string; reason: string } };
+  | { name: "ControllerLoadSkipped"; payload: { purl: string; reason: string } }
+  /**
+   * Real work has started for `purl` — an install, a compile or a transfer is
+   * about to run. This is the *only* in-progress signal, and it fires solely
+   * on the branch that does the work, so a warm start emits nothing rather
+   * than something a consumer has to take back. Closed by the matching
+   * `ControllerLoaded` / `ControllerLoadFailed`.
+   */
+  | { name: "ControllerWorkStarted"; payload: { purl: string; work: ControllerWorkKind } };
 
 /**
  * The dispatcher awaits each emission, so the callback may be async without
@@ -104,9 +146,13 @@ export interface ControllerLoaderOptions {
  * next candidate. User-code failures (`RuntimeError("ERR_CONTROLLER_BUILD_FAILED" | "ERR_CONTROLLER_INVALID")`)
  * fail hard regardless of remaining candidates.
  *
- * Lifecycle events are emitted per *attempt*, so a fallback chain produces one
- * `ControllerLoading` per candidate tried plus a final `ControllerLoaded` (or
- * `ControllerLoadFailed`) for the one that won.
+ * Lifecycle events follow resolution: a candidate this environment cannot host
+ * produces a `ControllerLoadSkipped` and nothing else, and only the candidate
+ * that resolved gets a `ControllerLoading` (carrying its resolve `source`)
+ * followed by `ControllerLoaded` / `ControllerLoadFailed`. In between, the
+ * sub-loader announces each branch that makes the caller wait as
+ * `ControllerWorkStarted` — the only in-progress signal, and the only one that
+ * cannot be emitted for a warm start.
  */
 export class ControllerLoader {
   private readonly emit: ControllerLoaderEmit | undefined;
@@ -132,56 +178,28 @@ export class ControllerLoader {
     artifact?: ModuleArtifact,
     libraries: SiblingLibraryMap = NO_SIBLING_LIBRARIES,
   ): Promise<ControllerInstance> {
-    if (!purlCandidates || purlCandidates.length === 0) {
-      throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", "Missing controller PURL candidates");
-    }
-    const effectivePolicy = policy ?? DEFAULT_POLICY;
-    const ordered = orderCandidates(purlCandidates, effectivePolicy);
-    if (ordered.length === 0) {
-      throw new RuntimeError(
-        "ERR_CONTROLLER_NOT_FOUND",
-        `No controllers match runtime selection [${effectivePolicy.load.join(", ")}]; declared: ${purlCandidates.join(", ")}`,
-      );
-    }
-
-    const errors: string[] = [];
-    for (const purl of ordered) {
-      await this.emit?.({ name: "ControllerLoading", payload: { purl } });
-      const startedAt = Date.now();
-      try {
-        const { instance, source } = await this.dispatchOne(purl, baseUri, artifact, libraries);
-        await this.emit?.({
-          name: "ControllerLoaded",
-          payload: { purl, source, durationMs: Date.now() - startedAt },
-        });
-        return instance;
-      } catch (err) {
-        if (err instanceof ControllerEnvMissingError) {
-          errors.push(`${purl}: ${err.message}`);
-          // Env-missing isn't a hard failure — the dispatcher will try the
-          // next candidate. We still emit a terminal event for *this* attempt
-          // so consumers (notably the CLI progress renderer) can close out
-          // the UI state opened by the matching ControllerLoading. Without
-          // this, every fallback attempt would leak a pending `⬇` line.
-          await this.emit?.({
-            name: "ControllerLoadSkipped",
-            payload: { purl, reason: err.message },
-          });
-          continue;
-        }
-        await this.emit?.({
-          name: "ControllerLoadFailed",
-          payload: { purl, error: err instanceof Error ? err.message : String(err) },
-        });
-        throw err;
-      }
-    }
-    const aggregated = `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`;
+    // Resolution — which is what installs, compiles and fetches — reports its
+    // own work and its own candidate fallthrough, so this is the import half
+    // and the announcement of what resolution decided.
+    const resolved = await this.resolve(purlCandidates, baseUri, policy, artifact, libraries);
     await this.emit?.({
-      name: "ControllerLoadFailed",
-      payload: { purl: ordered[ordered.length - 1], error: aggregated },
+      name: "ControllerLoading",
+      payload: { purl: resolved.purl, source: resolved.source },
     });
-    throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", aggregated);
+    try {
+      const instance = await resolved.importInstance();
+      await this.emit?.({
+        name: "ControllerLoaded",
+        payload: { purl: resolved.purl, source: resolved.source, durationMs: resolved.waitedMs() },
+      });
+      return instance;
+    } catch (err) {
+      await this.emit?.({
+        name: "ControllerLoadFailed",
+        payload: { purl: resolved.purl, error: err instanceof Error ? err.message : String(err) },
+      });
+      throw err;
+    }
   }
 
   /**
@@ -194,10 +212,12 @@ export class ControllerLoader {
    * registers fine and errors only when a resource of it is declared (matching
    * the Rust kernel's deferral).
    *
-   * Silent by design — no lifecycle events here; the caller emits
-   * ControllerLoading/Loaded around `importInstance` so the events fire when the
-   * load actually happens. A total resolution failure throws, mirroring
-   * {@link load}'s aggregated error.
+   * Emits `ControllerWorkStarted` whenever a sub-loader enters a branch that
+   * makes the caller wait, and `ControllerLoadSkipped` per candidate this
+   * environment cannot host. It does NOT announce the load itself: the caller
+   * emits ControllerLoading/Loaded around `importInstance`, so those fire when
+   * the load actually happens, with the resolved `source` already in hand. A
+   * total resolution failure throws, mirroring {@link load}'s aggregated error.
    */
   async resolve(
     purlCandidates: string[],
@@ -219,41 +239,54 @@ export class ControllerLoader {
     }
     const errors: string[] = [];
     for (const purl of ordered) {
+      // First work only: an install followed by a compile is one wait, and the
+      // clock the caller reads has to start where that wait did. The reporter
+      // outlives resolution because the import phase does work too.
+      let workStartedAt: number | undefined;
+      const report: ControllerWorkReporter = async (work) => {
+        workStartedAt ??= Date.now();
+        await this.emit?.({ name: "ControllerWorkStarted", payload: { purl, work } });
+      };
       try {
         const { source, importInstance } = await this.dispatchResolveOne(
           purl,
           baseUri,
           artifact,
           libraries,
+          report,
         );
-        return { purl, source, importInstance };
+        let importStartedAt: number | undefined;
+        return {
+          purl,
+          source,
+          importInstance: () => {
+            importStartedAt ??= Date.now();
+            return importInstance();
+          },
+          waitedMs: () => Date.now() - (workStartedAt ?? importStartedAt ?? Date.now()),
+        };
       } catch (err) {
         if (err instanceof ControllerEnvMissingError) {
           errors.push(`${purl}: ${err.message}`);
+          await this.emit?.({
+            name: "ControllerLoadSkipped",
+            payload: { purl, reason: err.message },
+          });
           continue;
         }
+        await this.emit?.({
+          name: "ControllerLoadFailed",
+          payload: { purl, error: err instanceof Error ? err.message : String(err) },
+        });
         throw err;
       }
     }
-    throw new RuntimeError(
-      "ERR_CONTROLLER_NOT_FOUND",
-      `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`,
-    );
-  }
-
-  private async dispatchOne(
-    purl: string,
-    baseUri: string,
-    artifact: ModuleArtifact | undefined,
-    libraries: SiblingLibraryMap,
-  ): Promise<{ instance: ControllerInstance; source: ControllerResolveSource }> {
-    const { source, importInstance } = await this.dispatchResolveOne(
-      purl,
-      baseUri,
-      artifact,
-      libraries,
-    );
-    return { instance: await importInstance(), source };
+    const aggregated = `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`;
+    await this.emit?.({
+      name: "ControllerLoadFailed",
+      payload: { purl: ordered[ordered.length - 1], error: aggregated },
+    });
+    throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", aggregated);
   }
 
   private async dispatchResolveOne(
@@ -261,15 +294,16 @@ export class ControllerLoader {
     baseUri: string,
     artifact: ModuleArtifact | undefined,
     libraries: SiblingLibraryMap,
+    report: ControllerWorkReporter,
   ): Promise<{ source: ControllerResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     if (purl.startsWith("pkg:npm")) {
-      return this.npmLoader.resolve(purl, baseUri);
+      return this.npmLoader.resolve(purl, baseUri, report);
     }
     if (purl.startsWith("pkg:cargo")) {
-      return this.napiLoader.resolve(purl, baseUri);
+      return this.napiLoader.resolve(purl, baseUri, report);
     }
     if (purl.startsWith("pkg:telo")) {
-      return this.bundleLoader.resolve(purl, baseUri, artifact, libraries);
+      return this.bundleLoader.resolve(purl, baseUri, artifact, libraries, report);
     }
     throw new ControllerEnvMissingError(`Unsupported PURL scheme: ${purl}`);
   }

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

@@ -7,7 +7,7 @@ import { PackageURL } from "packageurl-js";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { hostPlatformTarget, type ModuleArtifact } from "../bundle/module-artifact.js";
-import type { ControllerResolveSource } from "../controller-loader.js";
+import type { ControllerResolveSource, ControllerWorkReporter } from "../controller-loader.js";
 import { ControllerEnvMissingError } from "./napi-loader.js";
 import { REALM_COLLAPSE_NAMES } from "./realm.js";
 import {
@@ -485,6 +485,7 @@ export class BundleControllerLoader {
     baseUri: string,
     artifact?: ModuleArtifact,
     libraries: SiblingLibraryMap = NO_SIBLING_LIBRARIES,
+    report?: ControllerWorkReporter,
   ): Promise<{ source: ControllerResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     let parsed: PackageURL;
     try {
@@ -578,10 +579,17 @@ export class BundleControllerLoader {
         importInstance: async () => {
           let built: string;
           try {
+            // A dev build is a compile the caller waits on, and it is paid here
+            // rather than at resolve — which is why the work signal is not tied
+            // to the resolve phase. The reporter goes INTO the builder rather
+            // than wrapping the call: only the builder knows whether its
+            // content-addressed cache answered, and reporting a cache hit would
+            // put a line on screen for work nobody waited for.
             built = await buildControllerFromSource(
               sourceFile!,
               cacheRoot!,
               buildExternals(libraries, format),
+              report,
             );
           } catch (err) {
             if (!(err instanceof ControllerEnvMissingError)) throw err;
@@ -607,7 +615,7 @@ export class BundleControllerLoader {
     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 resolved = await artifact.materializeController(selector);
+      const resolved = await artifact.materializeController(selector, report);
       if (!resolved) {
         throw new ControllerEnvMissingError(
           `pkg:telo controller "${purl}": the module artifact ships no layer for ` +

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

@@ -8,6 +8,8 @@ import { fileURLToPath } from "url";
 import { promisify } from "util";
 
 import { hostEnv } from "../host-env.js";
+// Type-only, so the cycle with the dispatcher that imports this loader is erased.
+import type { ControllerWorkReporter } from "../controller-loader.js";
 
 const execFileAsync = promisify(execFile);
 const requireFromHere = createRequire(import.meta.url);
@@ -140,6 +142,7 @@ export class NapiControllerLoader {
   async resolve(
     purl: string,
     baseUri: string,
+    report?: ControllerWorkReporter,
   ): Promise<{ source: NapiResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     const [, , name, , qualifiers, entry] = PackageURL.parseString(purl);
     const localPath = (qualifiers as any)?.get("local_path");
@@ -199,6 +202,9 @@ export class NapiControllerLoader {
           const { rawModule } = await existingInFlight;
           return project(rawModule, entry, cratePath);
         }
+        // Nothing above this line compiles — the cache and the in-flight gate
+        // both return without cargo running.
+        await report?.("cargo-build");
         const buildPromise = build(cratePath, crateName, cacheKey);
         _napiInFlight.set(cacheKey, buildPromise);
         let rawModule: any;

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

@@ -1,4 +1,5 @@
 import { ControllerInstance, NOOP_LOGGER, type Logger } from "@telorun/sdk";
+import type { ControllerWorkReporter } from "../controller-loader.js";
 import { execFile } from "child_process";
 import * as crypto from "crypto";
 import * as fs from "fs/promises";
@@ -188,6 +189,7 @@ export class NpmControllerLoader {
   async resolve(
     purl: string,
     baseUri: string,
+    report?: ControllerWorkReporter,
   ): Promise<{ source: NpmResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     const parsed = PackageURL.fromString(purl);
     if (!parsed.name) {
@@ -199,7 +201,7 @@ export class NpmControllerLoader {
     // versions can coexist in one flat node_modules (see installAlias).
     const alias = installAlias(packageName, version);
 
-    const installRoot = await this.ensureInstallRoot();
+    const installRoot = await this.ensureInstallRoot(report);
     const resolved = await resolveInstallSpec(parsed, packageName, baseUri);
     const source = await this.installPackage(
       installRoot,
@@ -207,6 +209,7 @@ export class NpmControllerLoader {
       resolved.spec,
       resolved.kind,
       version,
+      report,
     );
     const subpath = parsed.subpath ?? null;
     return {
@@ -221,9 +224,9 @@ export class NpmControllerLoader {
    * `npm install` once, and return the absolute root path. Memoized for the
    * lifetime of this loader instance.
    */
-  private ensureInstallRoot(): Promise<string> {
+  private ensureInstallRoot(report?: ControllerWorkReporter): Promise<string> {
     if (this.rootReady) return this.rootReady;
-    this.rootReady = this.materializeInstallRoot().catch((err) => {
+    this.rootReady = this.materializeInstallRoot(report).catch((err) => {
       // Reset on failure so a follow-up call retries rather than caches the rejection.
       this.rootReady = undefined;
       throw err;
@@ -231,7 +234,7 @@ export class NpmControllerLoader {
     return this.rootReady;
   }
 
-  private async materializeInstallRoot(): Promise<string> {
+  private async materializeInstallRoot(report?: ControllerWorkReporter): Promise<string> {
     if (!this.entryUrl) {
       // Throw the env-missing variant so a mixed candidate list (e.g.
       // `pkg:npm/... + pkg:cargo/...`) still falls back to the next
@@ -325,6 +328,9 @@ export class NpmControllerLoader {
           2,
         ) + "\n",
       );
+      // Announced here rather than at the top of the resolve: everything above
+      // this line is a fast path that reuses the existing tree.
+      await report?.("npm-install");
       await runPackageManager(installRoot, [
         "install",
         "--no-audit",
@@ -383,6 +389,7 @@ export class NpmControllerLoader {
     spec: string,
     kind: SpecKind,
     requestedVersion: string | null,
+    report?: ControllerWorkReporter,
   ): Promise<NpmResolveSource> {
     const cacheKey = alias;
     if (this.installedSpecs.has(cacheKey)) return "cache";
@@ -466,6 +473,9 @@ export class NpmControllerLoader {
           }
         }
 
+        // Past every re-check: the package manager is about to run for real,
+        // which is the wait a caller wants reported.
+        await report?.("npm-install");
         await runPackageManager(installRoot, [
           "install",
           "--no-audit",

package/src/controller-loaders/source-bundle-builder.ts

@@ -4,6 +4,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+// Type-only, so this builder stays free of a runtime edge to the dispatcher.
+import type { ControllerWorkReporter } from "../controller-loader.js";
 
 import { readOwnerManifest } from "../bundle/module-manifest.js";
 import { ControllerEnvMissingError } from "./napi-loader.js";
@@ -295,6 +297,7 @@ export async function buildControllerFromSource(
   entryFile: string,
   cacheRoot: string,
   libraries: readonly SiblingLibrary[] = [],
+  report?: ControllerWorkReporter,
 ): Promise<string> {
   const cacheDir = path.join(cacheRoot, CACHE_DIR);
   const externals = externalSpecifiers(libraries);
@@ -309,6 +312,9 @@ export async function buildControllerFromSource(
 
   const inFlight = buildsInFlight.get(entryFile);
   if (inFlight) return inFlight;
+  // Below the content-addressed cache and the in-flight gate: from here esbuild
+  // really runs, which is the only branch worth reporting as a wait.
+  await report?.("source-build");
   const work = build(entryFile, cacheDir, libraries).finally(() =>
     buildsInFlight.delete(entryFile),
   );

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

@@ -161,6 +161,11 @@ class ResourceDefinition implements ResourceInstance {
       installRoot: ctx.getInstallRoot(),
       cacheRoot: host.getCacheRoot?.(),
       log: ctx.log,
+      // What resolution reports on its own: the work branches it enters, and
+      // the candidates it skipped. Routed through `ctx.emit` so they carry the
+      // same `<kind>.` namespace as the load events emitted below — a consumer
+      // pairs a wait with its outcome by that namespace.
+      emit: (event) => ctx.emit(event.name, event.payload as Record<string, unknown>),
     });
     // The artifact of the module that DECLARED this kind — a bundled controller
     // ships in its own module's payload, not the consumer's. It owns the pinned
@@ -199,8 +204,7 @@ class ResourceDefinition implements ResourceInstance {
             }
             throw err;
           });
-        await ctx.emit("ControllerLoading", { purl: resolved.purl });
-        const startedAt = Date.now();
+        await ctx.emit("ControllerLoading", { purl: resolved.purl, source: resolved.source });
         const instance = await resolved.importInstance().catch(async (err) => {
           await ctx.emit("ControllerLoadFailed", {
             purl: resolved.purl,
@@ -212,7 +216,7 @@ class ResourceDefinition implements ResourceInstance {
         await ctx.emit("ControllerLoaded", {
           purl: resolved.purl,
           source: resolved.source,
-          durationMs: Date.now() - startedAt,
+          durationMs: resolved.waitedMs(),
         });
       },
     );

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

@@ -7,6 +7,7 @@ import type {
 } from "@telorun/sdk";
 import { isCompiledValue } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
+import { celSelfView } from "../../evaluation-context.js";
 
 /** CEL variables that are only bound at call time (request handling, step
  *  chaining, error branches) — never at a template's init(). A persistent
@@ -168,7 +169,13 @@ export function createTemplateController(definition: {
             for (const key of path[1].split(".").slice(1)) cur = cur?.[key];
             return cur;
           }
-          return definingContext.expandWith(value, { self: getSelf() });
+          // CEL cannot read a member off a live instance, and a ref slot holds
+          // one after Phase-5 injection. `celSelfView` replaces each with its
+          // published reading, so `self.<ref>.<field>` answers exactly as
+          // `resources.<name>.<field>` does. The pure-`self.<path>` form above
+          // is navigated directly and still yields the instance itself, which is
+          // what a ref slot passed straight through (`connection:`) needs.
+          return definingContext.expandWith(value, { self: celSelfView(getSelf()) });
         }
         if (isRefSentinel(value)) {
           const source = value.source;
@@ -215,10 +222,10 @@ export function createTemplateController(definition: {
               throw capabilityError(entry, invokeTarget, "invoke", "Telo.Invocable");
             }
             const invokeInputs =
-              definition.inputs != null ? expand(definition.inputs, { self: getSelf(), inputs }) : inputs;
+              definition.inputs != null ? expand(definition.inputs, { self: celSelfView(getSelf()), inputs }) : inputs;
             const raw = await entry.instance.invoke(invokeInputs);
             if (definition.result == null) return raw;
-            return expand(definition.result, { self: getSelf(), result: raw });
+            return expand(definition.result, { self: celSelfView(getSelf()), result: raw });
           },
         }),
 
@@ -239,10 +246,10 @@ export function createTemplateController(definition: {
               throw capabilityError(entry, provideTarget, "provide", "Telo.Invocable");
             }
             const provideInputs: any =
-              definition.inputs != null ? expand(definition.inputs, { self: getSelf() }) : {};
+              definition.inputs != null ? expand(definition.inputs, { self: celSelfView(getSelf()) }) : {};
             const raw = await entry.instance.invoke(provideInputs);
             if (definition.result == null) return raw;
-            return expand(definition.result, { self: getSelf(), result: raw });
+            return expand(definition.result, { self: celSelfView(getSelf()), result: raw });
           },
         }),
 

package/src/dependency-injection.ts

@@ -1,4 +1,4 @@
-import { ResourceInstance, ResourceManifest, RuntimeError, stampRefIdentity } from "@telorun/sdk";
+import { ResourceInstance, ResourceManifest, RuntimeError } from "@telorun/sdk";
 
 /**
  * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal,
@@ -41,12 +41,12 @@ export function injectAtPath(
         `Local reference '${String(ref.name)}' is registered but not initialized yet (deferring to a later init pass)`,
       );
     }
-    // Tag the instance with the kind+name it resolved from, so a consumer that
-    // holds only the bare instance (an invoke-step target) can dispatch it
-    // through the traced chokepoint rather than calling `.invoke()` directly.
-    if (instance && typeof ref.kind === "string" && typeof ref.name === "string") {
-      stampRefIdentity(instance, ref.kind, ref.name);
-    }
+    // The identity is NOT stamped here. It is stamped at `create()`, the single
+    // instance-production site, which is also the only point where an instance
+    // and the context that DECLARED it are both in hand — here the context is
+    // the CONSUMER's, so a declaration site derived at this point would name
+    // whoever referenced the resource. A second write-once stamp competing for
+    // the same property would silently decide that by init order.
     return instance;
   }