@telorun/analyzer 0.60.0 → 0.61.0

package/dist/validate-module-artifact.js

@@ -1,5 +1,6 @@
 import { parseLayerIndex, LayerIndexError } from "./artifact-layer-index.js";
-import { ArtifactSelectorError, PLATFORM_AXES, selectorFromQualifiers, } from "./artifact-selector.js";
+import { ArtifactSelectorError, PLATFORM_AXES, selectorFromQualifiers, selectorKey, } from "./artifact-selector.js";
+import { readLibraryCandidates } from "./module-library.js";
 import { DiagnosticSeverity } from "./types.js";
 const SOURCE = "telo-analyzer";
 /**
@@ -30,9 +31,60 @@ export function validateModuleArtifact(manifests) {
     for (const manifest of manifests) {
         validateLayerIndex(manifest, out);
         validateControllerSelectors(manifest, out);
+        validateLibraryCandidates(manifest, out);
     }
     return out;
 }
+/**
+ * The `exports.code:` block on a `Telo.Library` doc.
+ *
+ * Reported here rather than left to the loader for the same reason a controller
+ * selector is: an entry that cannot be read names no entry point, so a
+ * consumer's bundle falls back to *inlining* the library — the module scope
+ * duplication this whole mechanism exists to remove — and it does so silently, on
+ * someone else's machine.
+ */
+function validateLibraryCandidates(manifest, out) {
+    // `Telo.Library` only. An application is a root with no importer, so it has no
+    // `exports:` block at all — and its schema is `additionalProperties: false`,
+    // so AJV already rejects the key by name in this same pass. A second
+    // diagnostic on that node would be two squiggles saying one thing.
+    if (manifest.kind !== "Telo.Library")
+        return;
+    const metadata = manifest.metadata;
+    const { candidates, problems } = readLibraryCandidates(manifest);
+    const resource = { kind: manifest.kind, name: metadata?.name };
+    for (const problem of problems) {
+        out.push({
+            severity: DiagnosticSeverity.Error,
+            code: "LIBRARY_CANDIDATE_INVALID",
+            source: SOURCE,
+            message: `Telo.Library/${metadata?.name ?? "(unnamed)"}: ${problem.origin}: ${problem.detail}`,
+            data: { resource, filePath: metadata?.source, path: "exports/code" },
+        });
+    }
+    // One specifier per selector: two candidates of one format claiming the same
+    // specifier leave the resolution ambiguous, and two specifiers for one format
+    // mean a consumer's import resolves by whichever candidate is read first.
+    const seen = new Map();
+    for (const candidate of candidates) {
+        const key = selectorKey(candidate.selector);
+        const first = seen.get(key);
+        if (first) {
+            out.push({
+                severity: DiagnosticSeverity.Error,
+                code: "LIBRARY_CANDIDATE_DUPLICATE",
+                source: SOURCE,
+                message: `Telo.Library/${metadata?.name ?? "(unnamed)"}: two 'exports.code' entries declare the ` +
+                    `selector ${key} ('${first.specifier}' and '${candidate.specifier}'). A module has one ` +
+                    `entry point per format — which is what makes "one specifier, one module scope" true.`,
+                data: { resource, filePath: metadata?.source, path: "exports/code" },
+            });
+            continue;
+        }
+        seen.set(key, candidate);
+    }
+}
 /** `local_path` names the source `path=` was built from, so a working copy runs
  *  with no build step. It is inert in a published artifact — which ships no
  *  `src/` — and contributes nothing to the selector, so it never affects which

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",

package/src/artifact-layer-index.ts

@@ -29,8 +29,10 @@
  */
 
 import {
+  LAYER_ROLES,
   isLayerRole,
   normalizeSelector,
+  roleCarriesSelector,
   selectorKey,
   selectorMatches,
   type ArtifactSelector,
@@ -46,7 +48,7 @@ const CONTENT_DIGEST = /^sha256-[A-Za-z0-9_-]{43}$/;
 
 export interface ArtifactLayer {
   role: LayerRole;
-  /** Present on `controller` layers only. */
+  /** Present on the code-bearing roles (`controller`, `library`) only. */
   selector?: ArtifactSelector;
   /** OCI blob digest — addresses the layer and verifies the transfer. */
   blob: string;
@@ -97,25 +99,35 @@ export function parseLayerIndex(value: unknown, describe = "layers"): ArtifactLa
       throw new LayerIndexError(`${where}: expected an object.`);
     }
     const entry = raw as Record<string, unknown>;
-    if (!isLayerRole(entry.role)) {
+    if (typeof entry.role !== "string" || entry.role === "") {
       throw new LayerIndexError(
-        `${where}: role must be one of 'controller', 'assets', 'common'; got ` +
-          `${entry.role === undefined ? "nothing" : `'${String(entry.role)}'`}.`,
+        `${where}: role is required and must be one of ${LAYER_ROLES.map((r) => `'${r}'`).join(", ")}; ` +
+          `got ${entry.role === undefined ? "nothing" : `'${String(entry.role)}'`}.`,
       );
     }
+    // A role this runtime does not know is SKIPPED, never rejected. Roles are
+    // added over time, and a runtime that cannot name one cannot need it — while
+    // throwing would make the whole manifest unreadable, so a module gaining a
+    // layer for a newer runtime would stop loading on an older one entirely
+    // rather than merely lacking that layer. The error stays for a structurally
+    // invalid entry, which is a malformed index rather than a newer one.
+    if (!isLayerRole(entry.role)) return;
     const role = entry.role;
 
     let selector: ArtifactSelector | undefined;
-    if (role === "controller") {
+    if (roleCarriesSelector(role)) {
       if (entry.selector === undefined) {
-        throw new LayerIndexError(`${where}: a controller layer must declare a selector.`);
+        throw new LayerIndexError(`${where}: a ${role} layer must declare a selector.`);
       }
       selector = normalizeSelector(entry.selector, where);
-      const key = selectorKey(selector);
+      // Scoped by role: a module's `js` controller layer and its `js` library
+      // layer are different layers with the same selector, and only a collision
+      // *within* one role means two layers claim one address.
+      const key = `${role}\0${selectorKey(selector)}`;
       if (seenSelectors.has(key)) {
         throw new LayerIndexError(
-          `${where}: a second controller layer claims the selector ${key}. ` +
-            `Each selector addresses exactly one layer.`,
+          `${where}: a second ${role} layer claims the selector ${selectorKey(selector)}. ` +
+            `Each selector addresses exactly one layer of a role.`,
         );
       }
       seenSelectors.add(key);
@@ -145,18 +157,39 @@ export function parseLayerIndex(value: unknown, describe = "layers"): ArtifactLa
 /** The singleton layer for a role, or undefined when the artifact has none. */
 export function singletonLayer(
   layers: readonly ArtifactLayer[],
-  role: Exclude<LayerRole, "controller">,
+  role: Exclude<LayerRole, "controller" | "library">,
 ): ArtifactLayer | undefined {
   return layers.find((l) => l.role === role);
 }
 
-/** Every controller layer matching `target`, in declaration order. Used by
- *  `telo install` to warm a cache for one platform. */
-export function matchControllerLayers(
+/** The layer of one code role carrying exactly `selector`, or undefined.
+ *
+ *  By exact key rather than by re-matching a host: the candidate being resolved
+ *  already *is* one selector, and it is by construction the key of the layer
+ *  that carries it. */
+export function codeLayerFor(
+  layers: readonly ArtifactLayer[],
+  role: Extract<LayerRole, "controller" | "library">,
+  selector: ArtifactSelector,
+): ArtifactLayer | undefined {
+  const key = selectorKey(selector);
+  return layers.find(
+    (l) => l.role === role && l.selector !== undefined && selectorKey(l.selector) === key,
+  );
+}
+
+/** Every code layer — controller and library alike — matching `target`, in
+ *  declaration order. Used by `telo install` to warm a cache for one platform:
+ *  a library layer is as much a prerequisite of an offline run as the controller
+ *  layer that imports it. */
+export function matchCodeLayers(
   layers: readonly ArtifactLayer[],
   target: PlatformTarget,
 ): ArtifactLayer[] {
   return layers.filter(
-    (l) => l.role === "controller" && l.selector !== undefined && selectorMatches(l.selector, target),
+    (l) =>
+      (l.role === "controller" || l.role === "library") &&
+      l.selector !== undefined &&
+      selectorMatches(l.selector, target),
   );
 }

package/src/artifact-selector.ts

@@ -25,16 +25,27 @@
  * published into OCI descriptors.
  */
 
-/** The role a layer plays in a module artifact. `controller` layers carry a
- *  selector; `assets` and `common` are singletons and carry none. */
-export type LayerRole = "controller" | "assets" | "common";
+/** The role a layer plays in a module artifact. `controller` and `library` layers
+ *  carry a selector; `assets` and `common` are singletons and carry none. */
+export type LayerRole = "controller" | "library" | "assets" | "common";
 
-export const LAYER_ROLES: readonly LayerRole[] = ["controller", "assets", "common"];
+export const LAYER_ROLES: readonly LayerRole[] = ["controller", "library", "assets", "common"];
 
 export function isLayerRole(value: unknown): value is LayerRole {
   return typeof value === "string" && (LAYER_ROLES as readonly string[]).includes(value);
 }
 
+/** The roles that hold executable code, and are therefore per format rather than
+ *  singletons. A `library` layer is per selector for the same reason a
+ *  `controller` layer is: a module's JS entry point and its future Rust one are
+ *  different files, and a consumer resolves the one its own runtime can import.
+ *  A singleton would be wrong the moment a second runtime ships. */
+export const CODE_LAYER_ROLES: readonly LayerRole[] = ["controller", "library"];
+
+export function roleCarriesSelector(role: LayerRole): boolean {
+  return (CODE_LAYER_ROLES as readonly string[]).includes(role);
+}
+
 /** The platform axes, in canonical order. Not a closed vocabulary of *values* —
  *  new architectures appear without a Telo release — only of axis names. */
 export const PLATFORM_AXES = ["os", "arch", "libc"] as const;

package/src/builtins.ts

@@ -33,6 +33,33 @@ const ASSETS_FILES_SCHEMA = {
   items: { type: "string" },
 };
 
+/** `exports.code` — the entry point a sibling module's controller bundle resolves
+ *  this library's bare specifier to, one per format.
+ *
+ *  Data rather than a package URL: `controllers:` needs a PURL because it can name
+ *  an ecosystem fetch (`pkg:npm`, `pkg:cargo`), while this always names a file the
+ *  module already ships, so the type/namespace segments would be constant noise —
+ *  and a query string is one opaque box to the visual editor. `format` plus the
+ *  platform axes build the same `ArtifactSelector` a controller candidate does.
+ *  Semantics and diagnostics live in `analyzer/nodejs/src/module-library.ts`. */
+const LIBRARY_CANDIDATES_SCHEMA = {
+  type: "array",
+  items: {
+    type: "object",
+    required: ["specifier", "format", "path"],
+    properties: {
+      specifier: { type: "string" },
+      format: { type: "string" },
+      path: { type: "string" },
+      source: { type: "string" },
+      os: { type: "string" },
+      arch: { type: "string" },
+      libc: { type: "string" },
+    },
+    additionalProperties: false,
+  },
+};
+
 /** The published layer index, written by `telo publish` (never hand-authored).
  *  One entry per layer except the manifest layer, which cannot list its own hash
  *  inside itself and is pinned by the importer's `#sha256-...` instead. Shape and
@@ -44,7 +71,7 @@ const LAYER_INDEX_SCHEMA = {
     type: "object",
     required: ["role", "blob", "integrity"],
     properties: {
-      role: { type: "string", enum: ["controller", "assets", "common"] },
+      role: { type: "string", enum: ["controller", "library", "assets", "common"] },
       selector: {
         type: "object",
         required: ["format"],
@@ -846,6 +873,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
               type: "array",
               items: { type: "string", not: { enum: ["variables", "secrets"] } },
             },
+            code: LIBRARY_CANDIDATES_SCHEMA,
           },
           additionalProperties: true,
         },

package/src/index.ts

@@ -222,12 +222,14 @@ export {
 } from "./sources/manifest-cache.js";
 export type { ManifestCacheCoords } from "./sources/manifest-cache.js";
 export {
+  CODE_LAYER_ROLES,
   LAYER_ROLES,
   PLATFORM_AXES,
   ArtifactSelectorError,
   describeSelector,
   isLayerRole,
   normalizeSelector,
+  roleCarriesSelector,
   selectorFromQualifiers,
   selectorKey,
   selectorMatches,
@@ -240,9 +242,16 @@ export type {
 } from "./artifact-selector.js";
 export { collectModuleFileClaims } from "./module-file-claims.js";
 export type { ModuleFileClaim } from "./module-file-claims.js";
+export { readLibraryCandidates } from "./module-library.js";
+export type {
+  LibraryCandidate,
+  LibraryCandidateProblem,
+  LibraryCandidates,
+} from "./module-library.js";
 export {
   LayerIndexError,
-  matchControllerLayers,
+  codeLayerFor,
+  matchCodeLayers,
   parseLayerIndex,
   singletonLayer,
 } from "./artifact-layer-index.js";

package/src/module-file-claims.ts

@@ -7,6 +7,7 @@ import {
 import { PackageURL } from "packageurl-js";
 import { parseAllDocuments } from "yaml";
 import { selectorFromQualifiers, selectorKey, type ArtifactSelector } from "./artifact-selector.js";
+import { readLibraryCandidates } from "./module-library.js";
 
 /**
  * One module-relative file a manifest names, and the artifact layer it belongs
@@ -51,6 +52,14 @@ interface ClaimBase {
  * controller claim with no selector that nothing would reject.
  */
 export type ModuleFileClaim =
+  | (ClaimBase & {
+      readonly role: "library";
+      readonly selector: ArtifactSelector;
+      /** The bare specifier a consumer's bundle imports this entry point by. */
+      readonly specifier: string;
+      /** The source `path` was built from, as on a controller claim. */
+      readonly localPath?: string;
+    })
   | (ClaimBase & {
       readonly role: "controller";
       readonly selector: ArtifactSelector;
@@ -121,6 +130,22 @@ function controllerClaims(json: unknown): ModuleFileClaim[] {
   return claims;
 }
 
+/** The library entry points one document's `library:` block names. Unlike a
+ *  controller entry — reached only when this module's own kinds instantiate —
+ *  this one is what a *sibling* resolves a bare specifier to, which is why it
+ *  gets its own layer rather than riding in the controller layer: a consumer
+ *  must reach it without loading this module's controllers. */
+function libraryClaims(json: unknown): ModuleFileClaim[] {
+  return readLibraryCandidates(json).candidates.map((candidate) => ({
+    role: "library",
+    path: candidate.path,
+    selector: candidate.selector,
+    specifier: candidate.specifier,
+    ...(candidate.localPath ? { localPath: candidate.localPath } : {}),
+    origin: candidate.origin,
+  }));
+}
+
 /** Claims contributed by tagged values, asked of the engine that owns each tag.
  *  The walk reaches every tagged scalar in the document, so an engine that
  *  embeds files is discovered wherever its tag was written.
@@ -146,7 +171,8 @@ function taggedClaims(json: unknown, registry: TemplatingEngineRegistry): Module
  *  their layers — dropping one would leave a platform's layer short a file it
  *  declared it needs. */
 function claimKey(claim: ModuleFileClaim): string {
-  const selector = claim.role === "controller" ? selectorKey(claim.selector) : "";
+  const selector =
+    claim.role === "controller" || claim.role === "library" ? selectorKey(claim.selector) : "";
   return `${claim.role}\0${selector}\0${claim.path}`;
 }
 
@@ -167,7 +193,11 @@ export function collectModuleFileClaims(
   const claims: ModuleFileClaim[] = [];
   for (const doc of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
     const json = doc.toJSON() as unknown;
-    for (const claim of [...controllerClaims(json), ...taggedClaims(json, registry)]) {
+    for (const claim of [
+      ...libraryClaims(json),
+      ...controllerClaims(json),
+      ...taggedClaims(json, registry),
+    ]) {
       const key = claimKey(claim);
       if (seen.has(key)) continue;
       seen.add(key);

package/src/module-library.ts

@@ -0,0 +1,208 @@
+/**
+ * A module's **exported code** — the `exports.code:` block on a `Telo.Library`
+ * doc, which names the entry point a *sibling module's* controller bundle
+ * resolves this module's bare specifier to.
+ *
+ * ```yaml
+ * exports:
+ *   kinds:
+ *     - Store
+ *   code:
+ *     - specifier: "@telorun/kv-store"
+ *       format: js
+ *       path: ./nodejs/kv-store.mjs
+ *       source: ./nodejs/src/index.ts
+ * ```
+ *
+ * ## Why it sits under `exports:`
+ *
+ * A library already declares what crosses its boundary — the kinds importers may
+ * name, the resource instances they may `!ref`. This is the same statement about
+ * its *code*, and it gates the same way: a specifier nobody declares resolves to
+ * nothing. Putting it beside them keeps one block for "reachable from outside"
+ * rather than a second top-level key whose name (`library:` on a `Telo.Library`)
+ * meant a different thing from the kind one line above it.
+ *
+ * ## Why it is not a package URL
+ *
+ * `controllers:` names a PURL because it must be able to say `pkg:npm/…` or
+ * `pkg:cargo/…` — an ecosystem fetch. This entry never fetches: it names a file
+ * the module already ships, so `pkg:telo/local/` would be three constant segments
+ * before the first real datum. What is left after removing them is exactly these
+ * fields, and as data they are visually editable, where a query string is one
+ * opaque text box.
+ *
+ * The **model** is unchanged: `format` plus the optional platform axes build the
+ * same `ArtifactSelector` a controller candidate does, so layer matching, platform
+ * fallthrough and lazy materialization are inherited whole.
+ *
+ * ## Why the specifier is declared here
+ *
+ * A bundle imports the bare specifier `@telorun/sql`; the consumer's manifest
+ * declares the dependency as `Sql: ../sql`. Something has to connect the two, and
+ * it is the *library* that says so, once, rather than each of its consumers:
+ *
+ * - the specifier is a property of the library — its name in a host language's
+ *   ecosystem — not of the relationship, so N consumers cannot disagree about it
+ *   and adding a consumer restates nothing;
+ * - it sits beside the format, which keeps runtime **derived, never declared**:
+ *   the entry says `format: js`, and a Rust entry carries `specifier:
+ *   telorun-sql` with no runtime-keyed map anywhere.
+ *
+ * **One specifier, one entry point.** Subpaths are deliberately not
+ * representable: reproducing npm's `exports` map inside the artifact would pull a
+ * package manager's resolution semantics into Telo, which is what the "only
+ * workspace modules are de-inlined" rule refuses on `kysely`'s behalf.
+ *
+ * `Telo.Application` has no `exports:` block at all — an application is a root
+ * with no importer, so nothing could resolve a specifier to it.
+ *
+ * Browser-safe: string work only. Whether the named file EXISTS is a separate
+ * question, asked by the Node-side caller that has a directory.
+ */
+
+import {
+  ArtifactSelectorError,
+  PLATFORM_AXES,
+  selectorFromQualifiers,
+  type ArtifactSelector,
+} from "./artifact-selector.js";
+
+/** Every key an entry may carry: the two locators, plus the selector axes. */
+const KNOWN_KEYS = new Set<string>(["specifier", "path", "source", "format", ...PLATFORM_AXES]);
+
+export interface LibraryCandidate {
+  /** The bare specifier a sibling's controller bundle imports this library by. */
+  readonly specifier: string;
+  /** Module-root-relative path of the built entry point. */
+  readonly path: string;
+  /** Module-root-relative TypeScript source it is built from (`source:`), when
+   *  the entry names one. Present only while the module is a working copy; a
+   *  published artifact ships no `src/`. */
+  readonly localPath?: string;
+  readonly selector: ArtifactSelector;
+  /** Where the entry was written, for diagnostics. */
+  readonly origin: string;
+}
+
+/** Why an `exports.code` entry could not be read. Returned rather than thrown so
+ *  the analyzer can report every entry of a block, and so a reader on the load
+ *  path can carry on with the entries that are well-formed. */
+export interface LibraryCandidateProblem {
+  readonly origin: string;
+  readonly detail: string;
+}
+
+export interface LibraryCandidates {
+  readonly candidates: LibraryCandidate[];
+  readonly problems: LibraryCandidateProblem[];
+}
+
+/** Normalize a `path` / `source` value to the manifest-relative POSIX form the
+ *  file selector returns, so membership is a string comparison. */
+function normalizeRelative(value: string): string {
+  return value.replace(/^\.\//, "").replace(/\\/g, "/");
+}
+
+function requiredString(
+  entry: Record<string, unknown>,
+  key: string,
+): { value: string } | { detail: string } {
+  const raw = entry[key];
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return { detail: `'${key}' is required and must be a non-empty string.` };
+  }
+  return { value: raw.trim() };
+}
+
+/**
+ * Read the `exports.code:` block off an owner document's JSON projection.
+ *
+ * Everything malformed is a problem rather than a silent skip: an entry that
+ * cannot be read names no entry point, so a consumer's bundle falls back to
+ * *inlining* the library — the duplicated module scope this whole mechanism
+ * exists to remove — and it does so on someone else's machine.
+ */
+export function readLibraryCandidates(ownerJson: unknown): LibraryCandidates {
+  const declared = (ownerJson as { exports?: { code?: unknown } } | null)?.exports?.code;
+  const candidates: LibraryCandidate[] = [];
+  const problems: LibraryCandidateProblem[] = [];
+  if (declared === undefined) return { candidates, problems };
+  if (!Array.isArray(declared)) {
+    return {
+      candidates,
+      problems: [{ origin: "exports.code", detail: "expected a list of entries." }],
+    };
+  }
+
+  declared.forEach((raw, index) => {
+    const origin = `exports.code[${index}]`;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      problems.push({ origin, detail: "expected an object." });
+      return;
+    }
+    const entry = raw as Record<string, unknown>;
+
+    const unknown = Object.keys(entry).filter((key) => !KNOWN_KEYS.has(key));
+    if (unknown.length > 0) {
+      // Reported, never ignored: an unrecognized platform axis would leave the
+      // entry platform-neutral and offer a single-platform file to every host.
+      problems.push({
+        origin,
+        detail:
+          `unknown ${unknown.length === 1 ? "key" : "keys"} ${unknown.map((k) => `'${k}'`).join(", ")}. ` +
+          `Known: ${[...KNOWN_KEYS].join(", ")}.`,
+      });
+      return;
+    }
+
+    const specifier = requiredString(entry, "specifier");
+    if ("detail" in specifier) {
+      problems.push({ origin, detail: specifier.detail });
+      return;
+    }
+    const file = requiredString(entry, "path");
+    if ("detail" in file) {
+      problems.push({ origin: `${origin} ('${specifier.value}')`, detail: file.detail });
+      return;
+    }
+    // Explicit rather than inferred from the file extension: a `.mjs` can be
+    // wasm glue, and an inference rule is something every other runtime's reader
+    // would have to copy exactly.
+    const format = requiredString(entry, "format");
+    if ("detail" in format) {
+      problems.push({ origin: `${origin} ('${specifier.value}')`, detail: format.detail });
+      return;
+    }
+
+    let selector: ArtifactSelector;
+    try {
+      selector = selectorFromQualifiers(format.value, entry, `${origin} ('${specifier.value}')`);
+    } catch (err) {
+      problems.push({
+        origin: `${origin} ('${specifier.value}')`,
+        detail: err instanceof ArtifactSelectorError ? err.message : String(err),
+      });
+      return;
+    }
+
+    const source = entry.source;
+    if (source !== undefined && (typeof source !== "string" || source.trim() === "")) {
+      problems.push({
+        origin: `${origin} ('${specifier.value}')`,
+        detail: "'source' must be a non-empty string when present.",
+      });
+      return;
+    }
+
+    candidates.push({
+      specifier: specifier.value,
+      path: normalizeRelative(file.value),
+      ...(typeof source === "string" ? { localPath: normalizeRelative(source.trim()) } : {}),
+      selector,
+      origin: `${origin} ('${specifier.value}')`,
+    });
+  });
+
+  return { candidates, problems };
+}

package/src/validate-module-artifact.ts

@@ -5,7 +5,9 @@ import {
   ArtifactSelectorError,
   PLATFORM_AXES,
   selectorFromQualifiers,
+  selectorKey,
 } from "./artifact-selector.js";
+import { readLibraryCandidates, type LibraryCandidate } from "./module-library.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -38,10 +40,64 @@ export function validateModuleArtifact(manifests: ResourceManifest[]): AnalysisD
   for (const manifest of manifests) {
     validateLayerIndex(manifest, out);
     validateControllerSelectors(manifest, out);
+    validateLibraryCandidates(manifest, out);
   }
   return out;
 }
 
+/**
+ * The `exports.code:` block on a `Telo.Library` doc.
+ *
+ * Reported here rather than left to the loader for the same reason a controller
+ * selector is: an entry that cannot be read names no entry point, so a
+ * consumer's bundle falls back to *inlining* the library — the module scope
+ * duplication this whole mechanism exists to remove — and it does so silently, on
+ * someone else's machine.
+ */
+function validateLibraryCandidates(manifest: ResourceManifest, out: AnalysisDiagnostic[]): void {
+  // `Telo.Library` only. An application is a root with no importer, so it has no
+  // `exports:` block at all — and its schema is `additionalProperties: false`,
+  // so AJV already rejects the key by name in this same pass. A second
+  // diagnostic on that node would be two squiggles saying one thing.
+  if (manifest.kind !== "Telo.Library") return;
+  const metadata = manifest.metadata as { name?: string; source?: string } | undefined;
+  const { candidates, problems } = readLibraryCandidates(manifest);
+  const resource = { kind: manifest.kind, name: metadata?.name };
+
+  for (const problem of problems) {
+    out.push({
+      severity: DiagnosticSeverity.Error,
+      code: "LIBRARY_CANDIDATE_INVALID",
+      source: SOURCE,
+      message: `Telo.Library/${metadata?.name ?? "(unnamed)"}: ${problem.origin}: ${problem.detail}`,
+      data: { resource, filePath: metadata?.source, path: "exports/code" },
+    });
+  }
+
+  // One specifier per selector: two candidates of one format claiming the same
+  // specifier leave the resolution ambiguous, and two specifiers for one format
+  // mean a consumer's import resolves by whichever candidate is read first.
+  const seen = new Map<string, LibraryCandidate>();
+  for (const candidate of candidates) {
+    const key = selectorKey(candidate.selector);
+    const first = seen.get(key);
+    if (first) {
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "LIBRARY_CANDIDATE_DUPLICATE",
+        source: SOURCE,
+        message:
+          `Telo.Library/${metadata?.name ?? "(unnamed)"}: two 'exports.code' entries declare the ` +
+          `selector ${key} ('${first.specifier}' and '${candidate.specifier}'). A module has one ` +
+          `entry point per format — which is what makes "one specifier, one module scope" true.`,
+        data: { resource, filePath: metadata?.source, path: "exports/code" },
+      });
+      continue;
+    }
+    seen.set(key, candidate);
+  }
+}
+
 /** `local_path` names the source `path=` was built from, so a working copy runs
  *  with no build step. It is inert in a published artifact — which ships no
  *  `src/` — and contributes nothing to the selector, so it never affects which