@telorun/analyzer 0.43.0 → 0.44.0

package/src/definition-registry.ts

@@ -1,4 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { canonicalTypeSchemaId } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import { KERNEL_BUILTINS } from "./builtins.js";
 import {
@@ -21,18 +22,21 @@ export class DefinitionRegistry {
    *  across analyze() calls and no unbounded growth across the process lifetime. */
   private readonly ajv = createAjv();
   private readonly registeredSchemaIds = new Set<string>();
+  /** The subset of `registeredSchemaIds` claimed by a kind's schema. Kinds and
+   *  named `Telo.Type`s share one `telo://<module>/<Name>` id space, so this is
+   *  what lets a colliding type name be reported instead of silently dropped. */
+  private readonly definitionSchemaIds = new Set<string>();
 
   private readonly defs = new Map<string, ResourceDefinition>();
   private readonly fieldMaps = new Map<string, ReferenceFieldMap>();
   /** Reverse inheritance index: parent kind → direct child kinds. */
   private readonly extendedBy = new Map<string, string[]>();
-  /** Module identity table: identity string → canonical module name.
-   *  "telo" → "Telo", "std/pipeline" → "pipeline", etc. */
+  /** DEPRECATED module identity table: identity string → canonical module name
+   *  ("std/pipeline" → "pipeline"). Serves only the legacy
+   *  `<namespace>/<module>#<Kind>` form of `x-telo-ref`, kept resolvable for
+   *  module versions published before constraints named their target by import
+   *  alias. Fed by `metadata.namespace`, which nothing else reads. */
   private readonly identityMap = new Map<string, string>();
-  /** Reverse identity table: canonical module name → full identity string.
-   *  "Telo" → "telo", "pipeline" → "std/pipeline", etc.
-   *  Used to compute definition $id values for the AJV schema store. */
-  private readonly reverseIdentityMap = new Map<string, string>();
 
   register(definition: ResourceDefinition): void {
     const { name, module: mod } = definition.metadata;
@@ -60,12 +64,11 @@ export class DefinitionRegistry {
     if (definition.extends) {
       this.addExtendedBy(definition.extends, key);
     }
-    // Auto-register the telo identity when any Telo built-in is registered.
+    // Auto-register the legacy telo identity when any Telo built-in is registered,
+    // so an already-published `x-telo-ref: "telo#Invocable"` still resolves.
     if (definition.kind === "Telo.Abstract" && mod === "Telo") {
       this.identityMap.set("telo", "Telo");
-      this.reverseIdentityMap.set("Telo", "telo");
     }
-    // If identity is already known, register the schema in AJV immediately.
     if (mod && definition.schema) {
       this.tryRegisterSchema(mod, name as string, definition.schema as Record<string, any>);
     }
@@ -80,50 +83,42 @@ export class DefinitionRegistry {
     }
   }
 
-  /** Register a module identity for x-telo-ref resolution.
-   *  Call once per module doc (Telo.Application or Telo.Library) when the manifest is loaded.
-   *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.
-   *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
+  /** DEPRECATED. Register a module identity so the legacy
+   *  `<namespace>/<module>#<Kind>` form of `x-telo-ref` still resolves for module
+   *  versions published before constraints named their target by import alias.
+   *  New manifests declare no namespace and need no identity — their constraints
+   *  are canonicalized to `<module>.<Kind>` before registration.
+   *
+   *  The "telo" identity is reserved for the built-in module and is populated
+   *  automatically when a `Telo.Abstract` registers. A namespace-less module must
+   *  not claim it: overwriting the entry would repoint every legacy `telo#…`
+   *  constraint at a module that declares no such kind, and the resulting
+   *  unresolvable ref reads as partial context rather than an error.
+   *
+   *  @param namespace  The module's `metadata.namespace`, or null when it declares none.
+   *  @param moduleName The module's `metadata.name` (e.g. "pipeline", "http-server"). */
   registerModuleIdentity(namespace: string | null, moduleName: string): void {
-    // The "telo" identity is reserved for the Telo built-in module and gets
-    // populated automatically when a Telo.Abstract definition registers (see
-    // `register` below). A user app / library without a namespace must NOT
-    // claim it — silently overwriting the built-in entry breaks every
-    // x-telo-ref that resolves through "telo#…". Concretely, the
-    // `Http.Api.routes[].handler` slot in the http-server schema carries
-    // `x-telo-ref: "telo#Invocable"`. If the entry application is, say,
-    // `Telo.Application/HelloApi` (no namespace), this method previously
-    // overwrote `"telo" → "Telo"` with `"telo" → "HelloApi"`. The handler's
-    // ref then resolved to a nonexistent `HelloApi.Invocable`, the
-    // kind-mismatch check inside `validate-references.ts` short-circuited
-    // on partial context, and the analyzer reported zero issues for a
-    // manifest that explodes at runtime. Skip non-Telo no-namespace modules;
-    // they have no x-telo-ref identity to declare anyway.
-    if (!namespace && moduleName !== "Telo") return;
-    const identity = namespace ? `${namespace}/${moduleName}` : "telo";
-    this.identityMap.set(identity, moduleName);
-    this.reverseIdentityMap.set(moduleName, identity);
-    // Retroactively register AJV schemas for definitions of this module already in the registry.
-    for (const def of this.defs.values()) {
-      if (def.metadata.module === moduleName && def.schema) {
-        this.tryRegisterSchema(
-          moduleName,
-          def.metadata.name as string,
-          def.schema as Record<string, any>,
-        );
-      }
-    }
+    if (!namespace || moduleName === "Telo") return;
+    this.identityMap.set(`${namespace}/${moduleName}`, moduleName);
   }
 
   /** Registers a named `Telo.Type` resource's schema under its canonical
    *  module-scoped URI `$id` (`telo://<module>/<name>`), so a sibling schema's
    *  `$ref: "telo://Self/<name>"` (rewritten to the canonical form by
    *  `resolveSchemaTypeRefs`) resolves during AJV compilation. Mirrors the
-   *  kernel type controller's `registerSchema(canonicalTypeSchemaId(...))`. */
-  registerNamedTypeSchema(id: string, schema: Record<string, any>): void {
-    if (this.registeredSchemaIds.has(id) || this.ajv.getSchema(id)) return;
+   *  kernel type controller's `registerSchema(canonicalTypeSchemaId(...))`.
+   *
+   *  Returns `false` when a kind schema in the same module already owns the id —
+   *  a name collision between a kind and a named type. Definitions register
+   *  first, so the type is the one that would be dropped, and every
+   *  `$ref: "telo://<module>/<Name>"` would then silently validate against the
+   *  kind's schema instead. The caller reports it; nothing is overwritten. */
+  registerNamedTypeSchema(id: string, schema: Record<string, any>): boolean {
+    if (this.definitionSchemaIds.has(id)) return false;
+    if (this.registeredSchemaIds.has(id) || this.ajv.getSchema(id)) return true;
     this.ajv.addSchema(schema, id);
     this.registeredSchemaIds.add(id);
+    return true;
   }
 
   /** True when a schema is registered under `id` (a canonical `telo://` type id
@@ -132,14 +127,6 @@ export class DefinitionRegistry {
     return this.registeredSchemaIds.has(id) || this.ajv.getSchema(id) !== undefined;
   }
 
-  /** Computes the $id for a definition schema: "<identity>/<TypeName>".
-   *  Returns undefined when the module identity is not yet registered. */
-  computeId(moduleName: string, typeName: string): string | undefined {
-    const identity = this.reverseIdentityMap.get(moduleName);
-    if (!identity) return undefined;
-    return `${identity}/${typeName}`;
-  }
-
   /** Validates data against a schema using this registry's AJV instance, which has all
    *  registered definition schemas loaded — enabling cross-module $ref resolution.
    *  A compile failure returns `[]` here; it is surfaced loudly (once, on the
@@ -172,37 +159,51 @@ export class DefinitionRegistry {
     }
   }
 
+  /** Registers a definition schema under the same module-scoped `telo://` id a
+   *  named `Telo.Type` uses, so a kind schema and a type schema are addressable
+   *  the same way and a `$ref` between them resolves at AJV compile time. One id
+   *  space per module: a kind and a named type may not share a name, which
+   *  `registerNamedTypeSchema` reports rather than resolving silently. */
   private tryRegisterSchema(
     moduleName: string,
     typeName: string,
     schema: Record<string, any>,
   ): void {
-    const id = this.computeId(moduleName, typeName);
-    if (!id || this.registeredSchemaIds.has(id)) return;
+    const id = canonicalTypeSchemaId(moduleName, typeName);
+    if (this.registeredSchemaIds.has(id)) {
+      this.definitionSchemaIds.add(id);
+      return;
+    }
     if (this.ajv.getSchema(id)) {
       throw new Error(`Duplicate definition schema $id: "${id}" is already registered`);
     }
     this.ajv.addSchema(schema, id);
     this.registeredSchemaIds.add(id);
+    this.definitionSchemaIds.add(id);
   }
 
-  /** Resolves an x-telo-ref string to a canonical registry kind key.
-   *  Splits on "#", looks up the left side in the identity table, and returns
-   *  "<canonicalModule>.<TypeName>".
+  /** Resolves an `x-telo-ref` constraint to a canonical registry kind key.
+   *
+   *  The constraint is already canonical `<module>.<Kind>`: alias-form values
+   *  (`KvStore.Store`, `Self.Store`, `Telo.Invocable`) are rewritten in the
+   *  declaring module's scope by `resolveSchemaRefKinds` before registration, so
+   *  no module context is needed here.
+   *
+   *  The legacy `<namespace>/<module>#<Kind>` form still resolves through the
+   *  identity table for module versions published before the alias form existed:
    *
-   *  "telo#Invocable"         → "Telo.Invocable"
-   *  "std/pipeline#Job"       → "pipeline.Job"
-   *  "std/http-server#Server" → "http-server.Server"
+   *    "telo#Invocable"         → "Telo.Invocable"
+   *    "std/http-server#Server" → "http-server.Server"
    *
-   *  Returns undefined when the string is malformed or the identity is not registered. */
+   *  Returns undefined when a legacy string is malformed or its identity was
+   *  never registered. */
   resolveRef(xTeloRef: string): string | undefined {
     const hash = xTeloRef.indexOf("#");
-    if (hash === -1 || hash === xTeloRef.length - 1) return undefined;
-    const identity = xTeloRef.slice(0, hash);
-    const typeName = xTeloRef.slice(hash + 1);
-    const moduleName = this.identityMap.get(identity);
+    if (hash === -1) return xTeloRef;
+    if (hash === xTeloRef.length - 1) return undefined;
+    const moduleName = this.identityMap.get(xTeloRef.slice(0, hash));
     if (!moduleName) return undefined;
-    return `${moduleName}.${typeName}`;
+    return `${moduleName}.${xTeloRef.slice(hash + 1)}`;
   }
 
   resolve(kind: string): ResourceDefinition | undefined {

package/src/loaded-types.ts

@@ -50,18 +50,25 @@ export interface LoadedModule {
 }
 
 /** Resolved Telo.Import edge: where the import points and what library
- *  identity it resolves to. Carrying name/namespace on the edge means
- *  `flattenForAnalyzer` can stamp `metadata.resolvedModuleName` /
- *  `resolvedNamespace` from this single source rather than re-deriving
- *  the target from manifest metadata, which would silently miss whenever
- *  a future projection forgets to stamp `metadata.source` consistently. */
+ *  identity it resolves to. Carrying the name on the edge means
+ *  `flattenForAnalyzer` can stamp `metadata.resolvedModuleName` from this
+ *  single source rather than re-deriving the target from manifest metadata,
+ *  which would silently miss whenever a future projection forgets to stamp
+ *  `metadata.source` consistently. */
 export interface ImportEdge {
   /** Canonical resolved URL of the target — a key into `modules`. */
   targetSource: string;
+  /** The import's `source` exactly as authored — a registry ref, an `oci://`
+   *  or `https://` ref, or a relative path. Version reconciliation keys on
+   *  this (minus its version), since it names the module's location
+   *  independently of what the module declares about itself. */
+  targetRef: string;
   /** Target library's `metadata.name`, or `null` when the target had no
    *  Telo.Library doc (an error case captured in `LoadedGraph.errors`). */
   targetModuleName: string | null;
-  /** Target library's `metadata.namespace` (or `null` when unset). */
+  /** DEPRECATED. Target library's `metadata.namespace`, or `null` when it
+   *  declares none. Feeds only the legacy `<namespace>/<module>#<Kind>` form
+   *  of `x-telo-ref`; nothing else reads it. */
   targetNamespace: string | null;
 }
 

package/src/manifest-loader.ts

@@ -317,6 +317,7 @@ export class Loader {
 
           aliases.set(alias, {
             targetSource: targetCanonical,
+            targetRef: importSource,
             targetModuleName,
             targetNamespace,
           });

package/src/reconcile-module-versions.ts

@@ -83,24 +83,55 @@ function compareVersions(a: ParsedVersion, b: ParsedVersion): number {
   return 0;
 }
 
-/** Read a loaded module's `namespace/name` identity, version, and raw owner
- *  text. Returns `null` for modules without a namespace: only a registry
- *  identity (`<namespace>/<name>`) is a stable cross-import key. Two namespace-
- *  less local libraries that merely share a `metadata.name` are distinct modules
- *  reached via distinct source URLs — reconciling them would drop one and break
- *  its kinds; the same local file reached via two paths is already collapsed by
- *  canonical-source dedup, so there is nothing left to reconcile here. */
-function moduleIdentityOf(mod: LoadedModule): ModuleIdentity | null {
+/** The location identity of an import ref: the ref with its version stripped.
+ *  Two refs share an identity when they address the same module at different
+ *  versions, whatever transport owns them:
+ *
+ *    "std/kv-store@0.3.0"             → "std/kv-store"
+ *    "oci://ghcr.io/acme/s3@1.2.0"    → "oci://ghcr.io/acme/s3"
+ *    "https://x.com/lib/telo.yaml"    → itself (a URL carries no version)
+ *
+ *  Returns `null` for a relative path, which addresses one file on the
+ *  publisher's disk and is therefore not a cross-import key: two local libraries
+ *  that merely agree on `metadata.name` are distinct modules, and reconciling
+ *  them would drop one and break its kinds. The same local file reached via two
+ *  paths is already collapsed by canonical-source dedup.
+ *
+ *  **What this key cannot relate.** It compares ref *spellings*, so it groups by
+ *  origin exactly and nothing else. Two consequences, both accepted:
+ *
+ *  - A module imported once by a registry ref and once by a relative path is two
+ *    groups, so a version skew between them is not hoisted. Keying on what the
+ *    module declares about itself would catch that case, but only by trusting a
+ *    self-declared identity — which is what this change removes, and which
+ *    cannot tell two same-named modules from different origins apart.
+ *  - A bare `std/kv-store@0.4.0` and the equivalent direct
+ *    `https://<registry>/std/kv-store/0.4.0/telo.yaml` are two groups. Relating
+ *    them needs the configured registry base, which this pure, browser-safe
+ *    function does not have. */
+function refIdentity(ref: string): string | null {
+  const base = ref.split("#")[0];
+  if (!base || base.startsWith(".") || base.startsWith("/") || base.startsWith("file:")) {
+    return null;
+  }
+  const lastSlash = base.lastIndexOf("/");
+  const at = base.lastIndexOf("@");
+  return at > lastSlash && at > 0 ? base.slice(0, at) : base;
+}
+
+/** Read a loaded module's version and raw owner text under the location
+ *  identity the import edge reached it by. The identity comes from the ref, not
+ *  from anything the module declares about itself — a module's own metadata
+ *  cannot distinguish two same-named modules published to different origins. */
+function moduleIdentityOf(mod: LoadedModule, identity: string): ModuleIdentity | null {
   const doc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind));
   if (!doc) return null;
-  const meta = doc.metadata as { name?: string; namespace?: string | null; version?: string };
-  const name = meta?.name;
-  if (typeof name !== "string" || name.length === 0) return null;
-  if (typeof meta.namespace !== "string" || meta.namespace.length === 0) return null;
+  const meta = doc.metadata as { name?: string; version?: string };
+  if (typeof meta?.name !== "string" || meta.name.length === 0) return null;
   const version = typeof meta.version === "string" ? meta.version : "";
   return {
     source: mod.owner.source,
-    identity: `${meta.namespace}/${name}`,
+    identity,
     version,
     parsed: parseVersion(version),
     text: mod.owner.text,
@@ -184,8 +215,8 @@ function hoistDiagnostic(
 }
 
 /**
- * Reconcile a loaded import graph so each module identity (`namespace/name`)
- * resolves to a single version. Within a shared major the highest version wins
+ * Reconcile a loaded import graph so each module location (an import ref minus
+ * its version) resolves to a single version. Within a shared major the highest version wins
  * (a non-lossy hoist, given Telo's additive-only pre-1.0 policy); a major
  * mismatch is a hard conflict. Mutates `importEdges` in place — every edge that
  * pointed at a losing source is repointed at the winner — so `flattenForAnalyzer`
@@ -199,10 +230,31 @@ export function reconcileModuleVersions(
   const overrides = new Map<string, string>();
   const diagnostics: AnalysisDiagnostic[] = [];
 
+  // Location identity per resolved module, taken from the ref that reached it.
+  // Two refs at different versions resolve to different canonical sources, so a
+  // source normally maps to exactly one identity; the entry module has no
+  // inbound edge and needs none (it is never reconciled against itself).
+  //
+  // One source CAN be reached by two spellings of the same location (a bare
+  // registry ref and the direct URL it resolves to). Both name the same module
+  // at the same version, so either identity groups it correctly — but the choice
+  // must not depend on edge iteration order, or the same graph could reconcile
+  // differently across runs. First edge wins.
+  const identityBySource = new Map<string, string>();
+  for (const aliasMap of importEdges.values()) {
+    for (const edge of aliasMap.values()) {
+      if (identityBySource.has(edge.targetSource)) continue;
+      const identity = refIdentity(edge.targetRef);
+      if (identity) identityBySource.set(edge.targetSource, identity);
+    }
+  }
+
   const groups = new Map<string, ModuleIdentity[]>();
   const infoBySource = new Map<string, ModuleIdentity>();
-  for (const mod of modules.values()) {
-    const info = moduleIdentityOf(mod);
+  for (const [source, mod] of modules) {
+    const identity = identityBySource.get(source);
+    if (!identity) continue;
+    const info = moduleIdentityOf(mod, identity);
     if (!info) continue;
     infoBySource.set(info.source, info);
     const list = groups.get(info.identity);

package/src/reference-field-map.ts

@@ -1,6 +1,7 @@
 /** An entry for a field that carries one or more x-telo-ref constraints. */
 export interface RefFieldEntry {
-  /** One or more canonical ref strings ("namespace/module#TypeName" or "telo#TypeName").
+  /** One or more canonical kind keys ("<module>.<Kind>"), or the deprecated
+   *  identity form ("<namespace>/<module>#<Kind>") for a legacy published module.
    *  Multiple entries arise from anyOf branches. */
   refs: string[];
   /** True when the field path traversed through at least one array (path contains "[]"). */

package/src/resolve-schema-ref-kinds.ts

@@ -0,0 +1,118 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+
+const REF_ANNOTATION = "x-telo-ref";
+
+/** Why an `x-telo-ref` constraint did not canonicalize.
+ *
+ *  - `legacy`  — the deprecated `<namespace>/<module>#<Kind>` identity form,
+ *                still resolved through the identity table.
+ *  - `unknown` — the prefix is not an alias in the declaring module's scope: a
+ *                typo, a missing `imports:` entry — or a value that was already
+ *                canonical, which the caller separates by asking the registry.
+ *  - `gated`   — the alias is known and the target owns the kind, but its
+ *                `exports.kinds` does not list it. */
+export type RefConstraintReason = "legacy" | "unknown" | "gated";
+
+/** An `x-telo-ref` constraint that did not canonicalize. */
+export interface RefConstraintIssue {
+  /** The constraint string exactly as authored. */
+  ref: string;
+  /** Dotted path to the annotated schema node within the doc, e.g.
+   *  `schema.properties.store`. Points the author at the slot, not just the doc. */
+  path: string;
+  /** The `Telo.Definition` / `Telo.Abstract` doc that declares the slot. */
+  manifest: ResourceManifest;
+  reason: RefConstraintReason;
+  /** For `gated`: the target module and the kinds it does export. */
+  gate?: { module: string; exported: string[] };
+  /** Aliases the declaring scope does know — the "did you mean" material for
+   *  an `unknown` prefix. */
+  knownAliases?: string[];
+}
+
+/** True for the legacy identity form, which is split on `#` by the identity table. */
+export function isLegacyRefIdentity(ref: string): boolean {
+  return ref.includes("#");
+}
+
+/**
+ * Rewrites the `x-telo-ref` constraints on one definition doc from the alias
+ * form (`KvStore.Store`, `Self.Store`, `Telo.Invocable`) to the canonical
+ * `<module>.<Kind>` key the definition registry is keyed by.
+ *
+ * `resolver` must be the scope of the module that DECLARES the definition, not
+ * the consumer's: an imported library names its dependencies by its own aliases.
+ * This mirrors how `extends:` and `capability:` are pre-resolved before
+ * registration, so the registry never needs module context to answer a ref query.
+ *
+ * Every constraint that does not canonicalize is returned, tagged with why. That
+ * matters more than it looks: an unresolved constraint leaves a string naming no
+ * registered kind, and the reference check treats an unknown target as partial
+ * context and skips it — so an unreported one would silently let the slot accept
+ * anything. The authored value is left in place either way, so a diagnostic
+ * quotes what the author actually wrote.
+ *
+ * An `unknown` result also covers an already-canonical value (`kv-store.Store`
+ * names a module, not an alias), which is what keeps the rewrite idempotent —
+ * the caller drops those by checking the definition registry once every kind is
+ * registered.
+ *
+ * The walk covers the whole doc rather than a fixed field list: a constraint can
+ * sit in `schema`, `inputType`, `outputType`, or a `$defs` entry nested in any of
+ * them, and rewriting one that appears in a template body's inline schema is
+ * correct too.
+ */
+export function resolveSchemaRefKinds(
+  definition: ResourceManifest,
+  resolver: Pick<AliasResolver, "resolveKindResult" | "knownAliases">,
+): RefConstraintIssue[] {
+  const issues: RefConstraintIssue[] = [];
+
+  const record = (ref: string, path: string): void => {
+    if (isLegacyRefIdentity(ref)) {
+      issues.push({ ref, path, manifest: definition, reason: "legacy" });
+      return;
+    }
+    const result = resolver.resolveKindResult(ref);
+    if (result.status === "ok") return;
+    issues.push(
+      result.status === "gated"
+        ? {
+            ref,
+            path,
+            manifest: definition,
+            reason: "gated",
+            gate: { module: result.module, exported: result.exported },
+          }
+        : {
+            ref,
+            path,
+            manifest: definition,
+            reason: "unknown",
+            knownAliases: resolver.knownAliases(),
+          },
+    );
+  };
+
+  const walk = (value: unknown, path: string): void => {
+    if (value === null || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach((item, i) => walk(item, `${path}[${i}]`));
+      return;
+    }
+    const obj = value as Record<string, unknown>;
+    const ref = obj[REF_ANNOTATION];
+    if (typeof ref === "string" && ref) {
+      const result = isLegacyRefIdentity(ref) ? null : resolver.resolveKindResult(ref);
+      if (result?.status === "ok") obj[REF_ANNOTATION] = result.kind;
+      else record(ref, path);
+    }
+    for (const key of Object.keys(obj)) {
+      walk(obj[key], path ? `${path}.${key}` : key);
+    }
+  };
+
+  walk(definition, "");
+  return issues;
+}

package/src/sources/manifest-cache.ts

@@ -12,12 +12,20 @@ export const MANIFEST_CACHE_BASE_URL = "https://manifests.telo.sh";
  *  stores per version — `{ transport, host, path, version }` — so the tracker's
  *  write key and the editor's read key come from the same function and never
  *  drift. `path` is the slash-separated repo/module path (multi-segment OCI
- *  repos nest as prefixes). */
+ *  repos nest as prefixes), empty for a module addressed at a host's root. */
 export interface ManifestCacheCoords {
   transport: string;
   host: string;
   path: string;
-  version: string;
+  /** Omit only when the ref carries no version to key by — a direct `https://`
+   *  URL addresses exactly one file, so its path alone is already unambiguous.
+   *  Every ref whose grammar has a version segment must supply it, or two
+   *  versions of one module would collide on a single key. */
+  version?: string;
+  /** File within the version directory. Defaults to the module manifest, which
+   *  is the only file the hub's bucket stores; the local install cache also
+   *  holds each `include:` partial, which is named here. */
+  file?: string;
 }
 
 /** True for a segment that would corrupt or escape the cache key space. */
@@ -26,15 +34,25 @@ function invalidSegment(segment: string): boolean {
 }
 
 /** Deterministic cache key for one module version:
- *  `<transport>/<host>/<path…>/<version>/telo.yaml`. Returns `null` when any
- *  coordinate is empty or would traverse out of the key space. */
+ *  `<transport>/<host>/<path…>/<version>/<file>`, where `version` is omitted
+ *  when the coordinates carry none and `file` defaults to the module manifest.
+ *  Returns `null` when any coordinate is empty or would traverse out of the key
+ *  space. */
 export function manifestCacheKey(coords: ManifestCacheCoords): string | null {
-  const { transport, host, path, version } = coords;
-  const segments = [transport, host, ...path.split("/"), version];
-  if (segments.some(invalidSegment) || transport.includes("/") || host.includes("/") || version.includes("/")) {
+  const { transport, host, path, version, file } = coords;
+  const segments = [transport, host, ...(path ? path.split("/") : [])];
+  if (version !== undefined) segments.push(version);
+  segments.push(file ?? DEFAULT_MANIFEST_FILENAME);
+  if (
+    segments.some(invalidSegment) ||
+    transport.includes("/") ||
+    host.includes("/") ||
+    (version !== undefined && version.includes("/")) ||
+    (file !== undefined && file.includes("/"))
+  ) {
     return null;
   }
-  return `${segments.join("/")}/${DEFAULT_MANIFEST_FILENAME}`;
+  return segments.join("/");
 }
 
 /** Cache coordinates for an `oci://host/repo@tag` ref. Returns `null` when the