@telorun/analyzer 0.60.0 → 0.62.0

package/src/schema-keywords.ts

@@ -0,0 +1,359 @@
+/**
+ * The JSON Schema vocabulary an author writes inside a manifest, as data.
+ *
+ * WHY THIS EXISTS. A schema-valued slot used to be declared `type: object` and
+ * nothing more, so every surface that reads a kind schema — completion, hover,
+ * the editor's field walk, AJV — knew only "some object". Autocompletion was
+ * dead from the first key, and a typo (`requred:`, `type: 5`) was carried all
+ * the way to a runtime validation failure that named the wrong thing.
+ *
+ * ONE SOURCE, TWO SURFACES. The maps below are the whole vocabulary; the
+ * fragments in `manifest-schemas.ts` are built FROM them, and completion reads
+ * them directly. A second hand-written list is exactly how the IDE's suggestions
+ * and the validator's rules would drift apart.
+ *
+ * WHY THE ANNOTATIONS ARE NOT IN THE VALIDATING FRAGMENT. `x-telo-*` keys are
+ * offered by completion but deliberately never appear as literal property names
+ * in the schema that gets hoisted into a manifest. Several passes walk a
+ * definition's schema testing every object for an annotation KEY
+ * (`resolveSchemaRefKinds`, `validate-ref-slots`, `validate-zone-slots`), and a
+ * `properties` map holding a key spelled `x-telo-ref` reads to them as an
+ * annotated node — inventing diagnostics about a slot the author never wrote.
+ * So the hoisted body stays open (`additionalProperties: true`, which admits
+ * every annotation) and the annotation vocabulary stays here, on the analyzer
+ * side of the boundary, where no manifest walk can reach it.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+
+import { X_TELO_TYPE } from "@telorun/sdk";
+import { ANNOTATION_KEYWORDS } from "./value-type-keyword.js";
+
+/** A keyword entry: the JSON Schema its VALUE must satisfy, carrying the title
+ *  and description completion and hover show. */
+export type SchemaKeywords = Record<string, Record<string, unknown>>;
+
+/** A JSON type name, as `type:` accepts it — one, or a list (`[string, "null"]`,
+ *  the spelling `CEL_NULLABLE_ACCESS` guards). */
+const TYPE_NAME = {
+  type: "string",
+  enum: ["object", "array", "string", "number", "integer", "boolean", "null"],
+};
+
+/**
+ * The draft-07 keywords, as a property map for a fragment named `self`.
+ *
+ * Parameterized by the fragment name because a schema's nested positions hold
+ * schemas of the SAME flavour: a property of a kind schema may carry
+ * annotations, a property of a data schema may not. Both recurse into
+ * themselves, and the document-local pointer is what the hoisting in
+ * `expandManifestFragments` makes resolvable.
+ */
+export function jsonSchemaKeywords(self: string): SchemaKeywords {
+  const schema = { $ref: `#/$defs/${self}` };
+  const schemaList = { type: "array", items: schema };
+
+  return {
+    // Shape
+    type: {
+      title: "Type",
+      description: "The JSON type this value must have, or a list of accepted types.",
+      anyOf: [TYPE_NAME, { type: "array", items: TYPE_NAME }],
+    },
+    properties: {
+      title: "Properties",
+      description: "Schema per named property of an object.",
+      type: "object",
+      additionalProperties: schema,
+    },
+    required: {
+      title: "Required",
+      description: "Property names that must be present.",
+      type: "array",
+      items: { type: "string" },
+    },
+    additionalProperties: {
+      title: "Additional properties",
+      description:
+        "`false` rejects any property not named above — which is what makes a typo an error rather than an ignored field.",
+      anyOf: [{ type: "boolean" }, schema],
+    },
+    patternProperties: {
+      title: "Pattern properties",
+      description: "Schema per regular expression matching a property name.",
+      type: "object",
+      additionalProperties: schema,
+    },
+    propertyNames: {
+      title: "Property names",
+      description: "Schema every property NAME must satisfy.",
+      ...schema,
+    },
+    items: {
+      title: "Items",
+      description: "Schema for each element of an array.",
+      anyOf: [schema, schemaList],
+    },
+    additionalItems: {
+      title: "Additional items",
+      description: "Schema for elements past a positional `items` list.",
+      anyOf: [{ type: "boolean" }, schema],
+    },
+    contains: {
+      title: "Contains",
+      description: "At least one element must satisfy this schema.",
+      ...schema,
+    },
+
+    // Composition
+    allOf: { title: "All of", description: "Every branch must match.", ...schemaList },
+    anyOf: { title: "Any of", description: "At least one branch must match.", ...schemaList },
+    oneOf: {
+      title: "One of",
+      description:
+        "Exactly one branch must match. Prefer `anyOf` when a branch declares a value type — a consumer that does not know the keyword reads the branch as matching everything, and only `anyOf` degrades gracefully.",
+      ...schemaList,
+    },
+    not: { title: "Not", description: "The value must NOT match this schema.", ...schema },
+    if: { title: "If", description: "Condition selecting `then` / `else`.", ...schema },
+    then: { title: "Then", description: "Applied when `if` matches.", ...schema },
+    else: { title: "Else", description: "Applied when `if` does not match.", ...schema },
+
+    // Values
+    enum: { title: "Enum", description: "The complete set of accepted values.", type: "array" },
+    const: { title: "Const", description: "The single accepted value." },
+    default: {
+      title: "Default",
+      description:
+        "Filled in when the value is absent. On an invocation contract this is applied at dispatch, so a caller may omit the field.",
+    },
+    examples: { title: "Examples", description: "Sample values, for documentation.", type: "array" },
+
+    // Numbers
+    minimum: { title: "Minimum", type: "number" },
+    maximum: { title: "Maximum", type: "number" },
+    exclusiveMinimum: { title: "Exclusive minimum", type: "number" },
+    exclusiveMaximum: { title: "Exclusive maximum", type: "number" },
+    multipleOf: { title: "Multiple of", type: "number", exclusiveMinimum: 0 },
+
+    // Strings
+    minLength: { title: "Min length", type: "integer", minimum: 0 },
+    maxLength: { title: "Max length", type: "integer", minimum: 0 },
+    pattern: { title: "Pattern", description: "Regular expression the string must match.", type: "string" },
+    format: {
+      title: "Format",
+      description: "Named string format (`date-time`, `uri`, `email`, …).",
+      type: "string",
+    },
+    contentMediaType: {
+      title: "Content media type",
+      description:
+        "Media type of the string's content (`application/javascript`). Drives the editor's code-widget language.",
+      type: "string",
+    },
+    contentEncoding: { title: "Content encoding", type: "string" },
+
+    // Arrays
+    minItems: { title: "Min items", type: "integer", minimum: 0 },
+    maxItems: { title: "Max items", type: "integer", minimum: 0 },
+    uniqueItems: { title: "Unique items", type: "boolean" },
+
+    // Objects
+    minProperties: { title: "Min properties", type: "integer", minimum: 0 },
+    maxProperties: { title: "Max properties", type: "integer", minimum: 0 },
+    dependencies: {
+      title: "Dependencies",
+      description: "Per property, the other properties it requires — or a schema to apply.",
+      type: "object",
+      additionalProperties: { anyOf: [{ type: "array", items: { type: "string" } }, schema] },
+    },
+
+    // Documentation and structure
+    title: { title: "Title", description: "Human-readable label for this value.", type: "string" },
+    description: {
+      title: "Description",
+      description: "What this value is, for the author reading the manifest.",
+      type: "string",
+    },
+    deprecated: { title: "Deprecated", type: "boolean" },
+    readOnly: { title: "Read only", type: "boolean" },
+    writeOnly: { title: "Write only", type: "boolean" },
+    $ref: {
+      title: "Reference",
+      description:
+        "Pointer to another schema: `#/$defs/<Name>` for one declared below, `telo:<module>/<Type>` for a named type a module declared.",
+      type: "string",
+    },
+    $defs: {
+      title: "Definitions",
+      description: "Named sub-schemas, private to this schema, referenced with `#/$defs/<Name>`.",
+      type: "object",
+      additionalProperties: schema,
+    },
+    definitions: {
+      title: "Definitions (draft-07)",
+      description: "Older spelling of `$defs`.",
+      type: "object",
+      additionalProperties: schema,
+    },
+    $comment: { title: "Comment", type: "string" },
+    $id: { title: "Id", type: "string" },
+    $schema: { title: "Schema dialect", type: "string" },
+  };
+}
+
+/**
+ * The `x-telo-*` annotation vocabulary — completion and hover only.
+ *
+ * TOTAL over {@link ANNOTATION_KEYWORDS} plus `x-telo-type`, which is what makes
+ * it a description of the existing list rather than a second copy of it: adding
+ * an annotation without a completion entry is a compile error here, and the
+ * first draft of this map — hand-written — had already silently dropped four
+ * annotations that live stdlib manifests use.
+ *
+ * Values are intentionally loose. What an annotation MEANS is checked by the
+ * pass that owns it (`validate-ref-slots`, `validate-zone-slots`,
+ * `validate-value-type-slots`), which reports in that annotation's own
+ * vocabulary; restating the shape here would give one mistake two diagnostics
+ * that disagree about what is wrong.
+ *
+ * A KNOWN BLIND SPOT, and not an oversight: several annotations
+ * (`x-telo-context`, `x-telo-error-context`, `x-telo-step-context`) hold JSON
+ * Schema themselves, and cannot be typed by the fragment this file feeds. A
+ * literal `x-telo-*` key inside a hoisted `properties` map reads to the
+ * annotation walkers as an annotated node, so the vocabulary has to stay out of
+ * anything that enters a manifest — which leaves an annotation's VALUE with
+ * neither validation nor completion. Closing it needs the walkers to distinguish
+ * a schema describing an annotation from an annotation, which nothing does yet.
+ */
+export const TELO_SCHEMA_ANNOTATIONS: Record<
+  (typeof ANNOTATION_KEYWORDS)[number] | typeof X_TELO_TYPE,
+  Record<string, unknown>
+> = {
+  "x-telo-eval": {
+    title: "Evaluation mode",
+    description:
+      "When `${{ }}` / `!cel` in this field is evaluated: `compile` at load, `runtime` per invocation. A CEL-bearing field MUST declare one, or the expression is read as a literal.",
+    type: "string",
+    enum: ["compile", "runtime"],
+  },
+  "x-telo-ref": {
+    title: "Reference slot",
+    description:
+      "This field holds a `!ref` to a resource — plus what the declaring resource DOES with it (`use`), which is what every topology analysis reads.",
+    anyOf: [{ type: "string" }, { type: "object" }],
+  },
+  "x-telo-type": {
+    title: "Value type",
+    description:
+      "What the value IS beyond JSON's types: `Telo.Bytes`, `Telo.Stream`, `Telo.TcpPort`, … Optionally parameterized (`{ name: Telo.Stream, of: Telo.Bytes }`).",
+    anyOf: [{ type: "string" }, { type: "object" }],
+  },
+  "x-telo-scope": {
+    title: "Execution scope",
+    description:
+      "JSON Pointer to a region whose `!ref`s resolve against this field's inline resources, created on entry and torn down on exit.",
+    anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+  },
+  "x-telo-context": {
+    title: "CEL context",
+    description: "The CEL variables in scope inside this field, as a JSON Schema. Analyzer-only.",
+    type: "object",
+  },
+  "x-telo-error-context": {
+    title: "Error context",
+    description: "Schema of the `error` CEL variable inside this field, at any nesting depth.",
+    type: "object",
+  },
+  "x-telo-step-context": {
+    title: "Step context",
+    description:
+      "On a step array: how to build typed `steps.<name>.result` from each item's invoked resource.",
+    type: "object",
+  },
+  "x-telo-schema-from": {
+    title: "Schema from",
+    description: "Derive this field's validation schema from a sibling ref's definition schema.",
+    type: "string",
+  },
+  "x-telo-value-schema-from": {
+    title: "Value schema from",
+    description:
+      "The value here must satisfy the type declared at the named field — checked for EVERY such slot, not only the branch a given input selects.",
+    type: "string",
+  },
+  "x-telo-bindings-from": {
+    title: "Bindings from",
+    description: "Merge the names declared in the named field's map into this field's CEL scope.",
+    type: "string",
+  },
+  "x-telo-context-from": {
+    title: "Context from",
+    description: "Merge the navigated value as a property map into this context node.",
+    type: "string",
+  },
+  "x-telo-context-from-root": {
+    title: "Context from root",
+    description: "Replace this context node's schema with the value navigated from the manifest root.",
+    type: "string",
+  },
+  "x-telo-context-from-ref-kind": {
+    title: "Context from ref kind",
+    description: "Type this node from a referenced kind's declared `inputType` / `outputType`.",
+    type: "string",
+  },
+  "x-telo-context-ref-from": {
+    title: "Context ref from",
+    description: "Type this node from the named manifest's field, falling back to its kind's.",
+    type: "string",
+  },
+  "x-telo-context-element-from": {
+    title: "Context element from",
+    description: "Type this binding from the ELEMENT of a sibling collection expression.",
+    type: "string",
+  },
+  "x-telo-context-collection-from": {
+    title: "Context collection from",
+    description:
+      "Type this binding from a sibling collection expression itself. Withheld when the collection is live — re-exposing a cursor being drained is what no member-access rule catches.",
+    type: "string",
+  },
+  "x-telo-provides-zone": {
+    title: "Provides zone",
+    description:
+      "This resource opens an execution zone; the annotated value is the CORRELATION KEY, never the zone (a zone is identified by the kind that provides it).",
+    anyOf: [{ type: "boolean" }, { type: "string" }],
+  },
+  "x-telo-requires-zone": {
+    title: "Requires zone",
+    description:
+      "This resource must be reached through the named providing kind's body, optionally correlated through an ordered pointer list.",
+    anyOf: [{ type: "string" }, { type: "object" }],
+  },
+  "x-telo-widget": {
+    title: "Editor widget",
+    description: "Render this field with a richer control — `code` gives a Monaco editor.",
+    type: "string",
+    enum: ["code"],
+  },
+  "x-telo-topology-role": {
+    title: "Topology role",
+    description: "Names this field's part in the kind's topology, for the editor's graph view.",
+    type: "string",
+  },
+  "x-telo-inline": {
+    title: "Inline",
+    description: "Renders this field's value inline in the editor rather than behind an accordion.",
+    type: "boolean",
+  },
+  "x-telo-outcome-list": {
+    title: "Outcome list",
+    description: "Marks an array of conditional response-rendering entries (`returns:`).",
+    anyOf: [{ type: "boolean" }, { type: "string" }],
+  },
+  "x-telo-catches-for": {
+    title: "Catches for",
+    description: "Names the field whose failures this branch list handles.",
+    type: "string",
+  },
+};

package/src/schema-region.ts

@@ -20,7 +20,18 @@
  * Browser-safe: no Node built-ins.
  */
 
-/** The kernel's schema-valued manifest keys. */
+/**
+ * The kernel's schema-valued manifest keys.
+ *
+ * TWO CONTAINMENT RULES READ THIS SET, and they are not the same rule. This
+ * file's own {@link isInSchemaRegion} asks "is this node inside a schema" and
+ * answers by ANCESTRY, for the reason argued above. `expandManifestFragments`
+ * asks a different question — "which node will a validator compile, so a
+ * `#/$defs/…` pointer written below it resolves" — and answers by the TOP-LEVEL
+ * key alone, because that is the object handed to AJV; a nested occurrence is a
+ * slot describing a field named `schema`, not a compile root. Neither rule is a
+ * weaker version of the other, so do not "fix" one to match.
+ */
 export const SCHEMA_REGION_KEYS: readonly string[] = [
   "schema",
   "status",

package/src/telo-version.ts

@@ -0,0 +1,9 @@
+// GENERATED by scripts/generate-telo-version.mjs — do not edit.
+//
+// The manifest SURFACE GENERATION this build implements, read from the linked
+// cli/kernel/sdk version. Distinct from this package's own npm version: that is
+// its release identity, this is the scale a module's `requires.telo` range is
+// written against, and every kernel in every language reports the same scale.
+
+/** The surface generation this analyzer implements. */
+export const TELO_SURFACE_VERSION = "0.77.0";

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { HostVersions } from "./requires-block.js";
+
 import type { ZoneModuleDocuments } from "./zone-module-documents.js";
 /** Matches LSP DiagnosticSeverity values exactly.
  *  https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticSeverity */
@@ -156,6 +158,36 @@ export interface AnalysisOptions {
    *  (on-disk stamp) attests that the manifests passed a real analyze
    *  pass at the same analyzer / kernel version. */
   skipValidation?: boolean;
+  /** The manifest SURFACE GENERATION the runtime performing this analysis
+   *  implements, against which every module's `requires.telo` range is checked.
+   *
+   *  Defaults to this build's own (`TELO_SURFACE_VERSION`), which is the right
+   *  answer for the kernel, the CLI and the editor alike. In a browser no kernel
+   *  is running, so the only well-posed question is whether the runtime *doing
+   *  the analysis* can read the module — and that is exactly the case where the
+   *  diagnostic is needed, since an editor too old to parse a construct
+   *  otherwise produces vocabulary errors it cannot explain.
+   *
+   *  The kernel deliberately does NOT override with its own package version.
+   *  The constant is generated from the linked kernel version, so the two are
+   *  the same number by construction; where they can drift — a kernel resolving
+   *  an older analyzer than it was released with — the analyzer is the half that
+   *  PARSES, and claiming a generation higher than the bundled parser implements
+   *  would be a claim the stack cannot honour.
+   *
+   *  So this exists for checking against a DIFFERENT target than oneself: a CI
+   *  matrix, or an editor setting naming the version a team deploys on.
+   *
+   *  Defaulted rather than optional-and-silent on purpose: there is no "caller
+   *  forgot to pass it, check silently skipped" path. */
+  teloVersion?: string;
+  /** Versions of the HOST the analysis is being performed for, against which a
+   *  module's `requires.host.*` ranges are checked.
+   *
+   *  Absent in a browser, where there is no host to speak for, and an axis with
+   *  no supplied version is skipped rather than guessed. The kernel and the CLI
+   *  supply it because they are the host. */
+  hostVersions?: HostVersions;
 }
 
 /** Pre-seeded state for incremental analysis. Passed to StaticAnalyzer.analyze() so it does

package/src/validate-identifier-names.ts

@@ -0,0 +1,173 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+import type { AliasResolver } from "./alias-resolver.js";
+import type { CallGraph } from "./call-graph.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import {
+  TYPE_LEVEL_DOC_KINDS,
+  checkName,
+  type NameLevel,
+  type NameViolation,
+} from "./identifier-name.js";
+import { type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Every author-written name in one pass — resource instances, kinds, modules,
+ * import aliases, step names and `variables` / `secrets` / `ports` keys. The
+ * rules and their rationale are in `identifier-name.ts`; this file only decides
+ * what each name IS and where to report it.
+ *
+ * One pass rather than a check bolted onto each surface's own validator: the
+ * rule is identical everywhere, and seven copies of it would drift the way the
+ * dot rule already had (enforced for resources, unenforced for steps, aliases
+ * and config declarations, which reach CEL through the same identifier space).
+ *
+ * **Step names come from the call graph, never from a walk of our own.** The
+ * graph already owns the analyzer's only step-array recursion and carries each
+ * step's name, owner and concrete path, which is exactly what a diagnostic
+ * needs. Re-walking would be a second answer to "what steps exist".
+ *
+ * **Scoped to the entry's own modules, at every tier including the errors.** A
+ * published dependency's naming is not the consumer's to fix, and reporting an
+ * error they cannot act on is worse than not reporting it — the standing
+ * precedent of `X_TELO_REF_UNRESOLVED` and `validate-extends`. The library's
+ * own author sees all of it when their module is analyzed as a root.
+ *
+ * Browser-safe.
+ */
+export function validateIdentifierNames(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  rootModules: Set<string>,
+  graph: CallGraph,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+
+  for (const manifest of manifests) {
+    const metadata = manifest.metadata as Record<string, unknown> | undefined;
+    const name = typeof metadata?.name === "string" ? metadata.name : undefined;
+    if (!manifest.kind || !name) continue;
+
+    // A name synthesized by inline extraction (`TestAdd_steps_0_invoke`) is
+    // derived from the author's own names, not written — reporting its shape
+    // would blame them for a spelling this pass's own pipeline chose.
+    if (metadata?.xTeloOrigin) continue;
+
+    const ownModule = metadata?.module as string | undefined;
+    if (ownModule && !rootModules.has(ownModule)) continue;
+
+    const level = levelFor(manifest, registry, aliases);
+    push(out, checkName(name, level, surfaceFor(manifest.kind)), {
+      kind: manifest.kind,
+      name,
+      filePath: metadata?.source as string | undefined,
+      path: "metadata.name",
+    });
+
+    // The module doc's config contract. Each key becomes `variables.<key>` /
+    // `secrets.<key>` / `ports.<key>` in CEL, so it lives in the same
+    // identifier space as a resource name and breaks the same way. An
+    // import's `variables:` / `secrets:` are deliberately NOT checked — those
+    // keys are the imported library's declarations, so a violation there is
+    // the library author's, reported when their module is analyzed as a root.
+    if (manifest.kind === "Telo.Application" || manifest.kind === "Telo.Library") {
+      for (const field of ["variables", "secrets", "ports"] as const) {
+        const block = (manifest as Record<string, unknown>)[field];
+        if (!block || typeof block !== "object" || Array.isArray(block)) continue;
+        for (const key of Object.keys(block as Record<string, unknown>)) {
+          push(out, checkName(key, "value", `${singular(field)} name`), {
+            kind: manifest.kind,
+            name,
+            filePath: metadata?.source as string | undefined,
+            path: `${field}.${key}`,
+          });
+        }
+      }
+    }
+  }
+
+  for (const node of graph.nodes.values()) {
+    if (node.type !== "step" || !node.name) continue;
+    const owner = graph.nodes.get(node.owner);
+    if (owner?.type !== "resource") continue;
+    const ownerMeta = owner.manifest.metadata as Record<string, unknown> | undefined;
+    if (ownerMeta?.xTeloOrigin) continue;
+    const ownModule = ownerMeta?.module as string | undefined;
+    if (ownModule && !rootModules.has(ownModule)) continue;
+
+    push(out, checkName(node.name, "value", "step name"), {
+      kind: owner.kind,
+      name: owner.name,
+      filePath: ownerMeta?.source as string | undefined,
+      path: `${node.path}.name`,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * A resource instance is value-level, EXCEPT when its capability is
+ * `Telo.Type`: a named shape has no runtime instance, is referenced from
+ * `inputType:` / `outputType:` type slots and resolves as
+ * `telo:<module>/<Name>`, so its name denotes a type despite being declared as
+ * a resource. Capability-driven rather than by kind name, so no resource kind
+ * is hardcoded here.
+ *
+ * An unresolvable kind falls back to value level — the honest default, since
+ * `UNDEFINED_KIND` already reports the real problem and guessing type level
+ * would stack a case error on top of it.
+ */
+function levelFor(
+  manifest: ResourceManifest,
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+): NameLevel {
+  if (TYPE_LEVEL_DOC_KINDS.has(manifest.kind as string)) return "type";
+  // The root resolver is the right one unconditionally: every manifest
+  // reaching here belongs to a root module, the others having been skipped.
+  const canonical = aliases.resolveKind(manifest.kind as string) ?? (manifest.kind as string);
+  return registry.resolve(canonical)?.capability === "Telo.Type" ? "type" : "value";
+}
+
+/** The noun phrase a diagnostic uses as its subject. */
+function surfaceFor(kind: string): string {
+  switch (kind) {
+    case "Telo.Application":
+    case "Telo.Library":
+      return "module name";
+    case "Telo.Definition":
+    case "Telo.Abstract":
+      return "kind name";
+    case "Telo.Import":
+      return "import alias";
+    default:
+      return "resource name";
+  }
+}
+
+function singular(field: "variables" | "secrets" | "ports"): string {
+  return field === "variables" ? "variable" : field === "secrets" ? "secret" : "port";
+}
+
+function push(
+  out: AnalysisDiagnostic[],
+  violation: NameViolation | undefined,
+  at: { kind: string; name: string; filePath: string | undefined; path: string },
+): void {
+  if (!violation) return;
+  out.push({
+    severity: violation.severity,
+    code: violation.code,
+    source: SOURCE,
+    message: `${at.kind}/${at.name}: ${violation.message}`,
+    data: {
+      resource: { kind: at.kind, name: at.name },
+      filePath: at.filePath,
+      path: at.path,
+    },
+  });
+}

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