@telorun/analyzer 0.72.0 → 0.74.0

package/src/validate-cel-context.ts

@@ -6,7 +6,9 @@ import {
   parseCanonicalTypeSchemaId,
 } from "@telorun/sdk";
 import { KERNEL_BUILTINS } from "./builtins.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import { withRefSlotsAsReadings } from "./ref-slot-reading.js";
+import { dispatchTargetOf } from "./template-body.js";
 // Where CEL is evaluated is one reader (`eval-paths.ts`), and the region half of
 // it moved there so the scope walk and the `x-telo-eval` walk answer the same
 // question in one place. Re-exported: this module is where every existing
@@ -51,6 +53,9 @@ export interface ContextResolveOpts {
   aliases?: {
     resolveKind(kind: string): string | undefined;
   };
+  /** Per-declaring-module alias tables, so a kind read off a forwarded
+   *  definition resolves in the module that wrote it. */
+  aliasesByModule?: ReadonlyMap<string, { resolveKind(kind: string): string | undefined }>;
   allManifests?: Record<string, any>[];
 }
 
@@ -334,18 +339,20 @@ function collectionBindingWithheld(
  *   Example: `properties.self.x-telo-context-from-root: "schema"` reads
  *   `manifestRoot.schema` and uses it as the schema of the `self` CEL variable.
  *
- * - `x-telo-context-from-ref-kind`: reads a kind name from `manifestRoot.<refPath>`,
- *   resolves it via the definition registry, and returns that kind's `<field>` schema
- *   (e.g. `outputType`/`inputType`). Used to type `result` against the dispatch
- *   target's declared output shape.
+ * - `x-telo-context-from-ref-kind`: reads a KIND from `manifestRoot.<refPath>` —
+ *   a field holding a kind name, or a definition's dispatch slot holding a
+ *   `!ref` to a `resources:` entry (whose kind it is) — and returns the
+ *   `<field>` schema (e.g. `outputType`/`inputType`) the entry itself declares,
+ *   else the one the kind's definition declares. Used to type `result` against
+ *   the dispatch target's declared output shape.
  *
  *   Syntax: `<refPath>#<field>` — slashes traverse the manifest tree.
  *
- *   Example: `x-telo-context-from-ref-kind: "provide/kind#outputType"` reads
- *   `manifestRoot.provide.kind` as a kind name, looks up the kind's Telo.Definition,
- *   and returns the `outputType` schema.
+ *   Example: `x-telo-context-from-ref-kind: "provide#outputType"` resolves
+ *   `manifestRoot.provide` (`!ref source`) to the entry named `source`, and
+ *   returns its `outputType` schema, or its kind's.
  *
- *   Accepts either a single string or an array of strings. With an array, paths
+ *   Accepts either a single string or an array of strings. With an array, slots
  *   are tried in order and the first one that resolves to a usable schema wins —
  *   used by `result:` to find its dispatch target under whichever entry-point
  *   field (`provide:` or `invoke:`) the definition declares.
@@ -370,7 +377,8 @@ export function resolveContextAnnotations(
   const normalizedOpts: ContextResolveOpts = Array.isArray(opts)
     ? { allManifests: opts }
     : (opts ?? {});
-  const { manifestRoot = manifestItem, defs, aliases, allManifests } = normalizedOpts;
+  const { manifestRoot = manifestItem, defs, aliases, aliasesByModule, allManifests } =
+    normalizedOpts;
 
   const from = schema["x-telo-context-from"] as string | undefined;
   if (from) {
@@ -459,26 +467,38 @@ export function resolveContextAnnotations(
       }
     }
     if (defs) {
+      // The kind is read off THIS document, so it is spelled in the alias scope
+      // of the module that declared it — a library's dispatch target is written
+      // through an import the consumer has no reason to have.
+      const scope = moduleAliasScope(
+        (manifestRoot as { metadata?: { module?: unknown } }).metadata,
+        aliases,
+        aliasesByModule,
+      );
       for (const fromRefKind of fromRefKinds) {
         const hashIdx = fromRefKind.indexOf("#");
         if (hashIdx <= 0) continue;
         const refPath = fromRefKind.slice(0, hashIdx);
         const field = fromRefKind.slice(hashIdx + 1);
-        const kindValue = navigatePath(manifestRoot, refPath.split("/"));
-        if (typeof kindValue !== "string" || kindValue.length === 0) continue;
-        const canonical = aliases?.resolveKind(kindValue) ?? kindValue;
-        const def = defs.resolve(canonical);
-        const typeField = def
-          ? (def as Record<string, unknown>)[field]
-          : undefined;
+        const target = kindAtPath(manifestRoot, refPath);
+        if (!target) continue;
+        // The entry's own field first — a per-instance narrowing (`outputType:`
+        // on the entry) is what the kernel binds — then the kind's.
+        const own = target.entry?.[field];
+        const ownResolved = own !== undefined ? resolveTypeFieldToSchema(own, allManifests ?? []) : undefined;
+        if (ownResolved && typeof ownResolved === "object") return ownResolved;
+        const canonical = scope?.resolveKind(target.kind) ?? target.kind;
+        const def = defs.resolve(canonical) ?? defs.resolve(target.kind);
+        const typeField = def ? (def as Record<string, unknown>)[field] : undefined;
         const resolved = resolveTypeFieldToSchema(typeField, allManifests ?? []);
         if (resolved && typeof resolved === "object") {
           return resolved;
         }
       }
     }
-    // Open fallback so unresolved types never produce false-positive CEL diagnostics.
-    return { type: "object", additionalProperties: true };
+    // Untyped (`dyn`) so an unresolved type never produces a false-positive CEL
+    // diagnostic; an open object would still type as `map` and refuse `acc + x`.
+    return {};
   }
 
   const refFrom = schema["x-telo-context-ref-from"] as string | undefined;
@@ -597,6 +617,28 @@ function navigatePath(obj: unknown, segments: string[]): unknown {
   return cur;
 }
 
+/** The kind an `x-telo-context-from-ref-kind` path names: a field holding a
+ *  kind NAME (`targetKind`), or a definition's dispatch slot holding a `!ref`
+ *  to a `resources:` entry, which carries the kind — and, where it narrows
+ *  one, the contract field itself. */
+export function kindAtPath(
+  manifestRoot: Record<string, any>,
+  refPath: string,
+): { kind: string; entry?: Record<string, any> } | undefined {
+  const segments = refPath.split("/");
+  const value = navigatePath(manifestRoot, segments);
+  if (typeof value === "string") return value.length > 0 ? { kind: value } : undefined;
+  // The dispatch-slot reading is a fact about ONE built-in document, not about
+  // the annotation: `resources:` is a `Telo.Definition`'s entry list. The
+  // annotation itself is generic vocabulary any kind may declare, and without
+  // this gate a third-party kind whose own `resources:` array means something
+  // else would have a slot silently resolved against it — a wrong answer with
+  // nothing reporting it, which is worse than no answer.
+  if (segments.length !== 1 || manifestRoot.kind !== "Telo.Definition") return undefined;
+  const dispatch = dispatchTargetOf(manifestRoot, segments[0]!);
+  return dispatch ? { kind: dispatch.kind, entry: dispatch.entry } : undefined;
+}
+
 /**
  * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
  * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —

package/src/validate-exports.ts

@@ -0,0 +1,185 @@
+import { nearestName } from "./nearest-name.js";
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { parseExportEntry } from "./flatten-for-analyzer.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * A LIBRARY'S EXPORT LIST IS CHECKED WHERE IT IS WRITTEN.
+ *
+ * `exports.kinds` and `exports.resources` are a library's public contract, and
+ * they were read as a GATE only: a listed name resolved when a consumer asked
+ * for it, and one that named nothing failed in the consumer's file
+ * (`UNDEFINED_KIND` on `kind: L.Client`, with nothing wrong in that file) while
+ * the author who could fix it saw a clean check. Both entries are resolved here,
+ * against what the library declares:
+ *
+ *  - a bare kind names a `Telo.Definition` / `Telo.Abstract` of this module, and
+ *    `Alias.Kind` re-exports through an import declared in this file
+ *    (`EXPORT_KIND_UNKNOWN`). The one mistake that reads as intended — a bare
+ *    name that IS a kind, of an imported module — gets the re-export spelling
+ *    in its message, because a clean check was read as confirmation it worked;
+ *  - a bare instance names a resource declared in this module, and
+ *    `Alias.name` an instance the aliased import exports
+ *    (`EXPORT_RESOURCE_UNKNOWN`).
+ *
+ * Runs on the library as an ENTRY — a consumer's flattened analysis drops the
+ * library doc, and the list is not the consumer's to fix. Browser-safe.
+ */
+export function validateExports(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  rootModules: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+
+  for (const lib of manifests) {
+    if (lib.kind !== "Telo.Library") continue;
+    const moduleName = lib.metadata?.name as string | undefined;
+    if (!moduleName || !rootModules.has(moduleName)) continue;
+    const exports = (lib as { exports?: { kinds?: unknown; resources?: unknown } }).exports;
+    if (!exports || typeof exports !== "object") continue;
+    const filePath = (lib.metadata as { source?: string } | undefined)?.source;
+    const resource = { kind: lib.kind, name: moduleName };
+
+    const own = (m: ResourceManifest): boolean => {
+      const mod = (m.metadata as { module?: string } | undefined)?.module;
+      return mod === undefined || mod === moduleName;
+    };
+    const declaredKinds = new Set<string>();
+    const instances = new Set<string>();
+    const importAliases = new Map<string, string | undefined>();
+    const forwardedByModule = new Map<string, Set<string>>();
+    for (const m of manifests) {
+      const name = m.metadata?.name;
+      if (typeof name !== "string") continue;
+      const meta = m.metadata as {
+        module?: string;
+        forwardedExport?: boolean;
+        resolvedModuleName?: string;
+      };
+      if (meta.forwardedExport && meta.module) {
+        let set = forwardedByModule.get(meta.module);
+        if (!set) forwardedByModule.set(meta.module, (set = new Set()));
+        set.add(name);
+        continue;
+      }
+      if (!own(m)) continue;
+      if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") declaredKinds.add(name);
+      else if (m.kind === "Telo.Import") importAliases.set(name, meta.resolvedModuleName);
+      else if (m.kind !== "Telo.Library" && m.kind !== "Telo.Application") instances.add(name);
+    }
+
+    const report = (code: string, path: string, message: string, fix?: string) =>
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code,
+        source: SOURCE,
+        message: `Telo.Library/${moduleName}: ${message}`,
+        data: { resource, filePath, path, ...(fix ? { fix: { replacement: fix } } : {}) },
+      });
+
+    const kinds = exports.kinds;
+    if (Array.isArray(kinds)) {
+      kinds.forEach((entry, i) => {
+        if (typeof entry !== "string") return;
+        const path = `exports.kinds[${i}]`;
+        const { alias, name } = parseExportEntry(entry);
+        if (alias) {
+          if (!importAliases.has(alias)) {
+            report(
+              "EXPORT_KIND_UNKNOWN",
+              path,
+              `'exports.kinds: ${entry}' re-exports through '${alias}', which is not an import ` +
+                `of this library. Imports: ${[...importAliases.keys()].join(", ") || "(none)"}.`,
+            );
+            return;
+          }
+          const canonical = aliases.resolveKind(entry);
+          if (canonical && !registry.resolve(canonical)) {
+            report(
+              "EXPORT_KIND_UNKNOWN",
+              path,
+              `'exports.kinds: ${entry}' names no kind '${name}' exported by '${alias}'.`,
+            );
+          }
+          return;
+        }
+        if (declaredKinds.has(name)) return;
+        // The natural first attempt at a re-export: the imported kind's bare
+        // suffix. It resolves as a kind — just not as one this library owns.
+        const viaImport = [...importAliases.keys()].find((a) => {
+          const canonical = aliases.resolveKind(`${a}.${name}`);
+          return canonical !== undefined && registry.resolve(canonical) !== undefined;
+        });
+        if (viaImport) {
+          report(
+            "EXPORT_KIND_UNKNOWN",
+            path,
+            `'exports.kinds: ${name}' is not a kind this library declares — it is ` +
+              `'${viaImport}.${name}', an imported kind. Re-export it as '${viaImport}.${name}', ` +
+              `or declare a local kind that extends it.`,
+            `${viaImport}.${name}`,
+          );
+          return;
+        }
+        const suggestion = nearestName(name, [...declaredKinds]);
+        report(
+          "EXPORT_KIND_UNKNOWN",
+          path,
+          `'exports.kinds: ${name}' names no Telo.Definition or Telo.Abstract of this library. ` +
+            `Declared: ${[...declaredKinds].join(", ") || "(none)"}.` +
+            (suggestion ? ` Did you mean '${suggestion}'?` : ""),
+          suggestion,
+        );
+      });
+    }
+
+    const resources = exports.resources;
+    if (Array.isArray(resources)) {
+      resources.forEach((entry, i) => {
+        if (typeof entry !== "string") return;
+        const path = `exports.resources[${i}]`;
+        const { alias, name } = parseExportEntry(entry);
+        if (alias) {
+          if (!importAliases.has(alias)) {
+            report(
+              "EXPORT_RESOURCE_UNKNOWN",
+              path,
+              `'exports.resources: ${entry}' re-exports through '${alias}', which is not an ` +
+                `import of this library. Imports: ${[...importAliases.keys()].join(", ") || "(none)"}.`,
+            );
+            return;
+          }
+          const targetModule = importAliases.get(alias);
+          const exported = targetModule ? forwardedByModule.get(targetModule) : undefined;
+          if (exported && !exported.has(name)) {
+            report(
+              "EXPORT_RESOURCE_UNKNOWN",
+              path,
+              `'exports.resources: ${entry}' names no instance '${name}' exported by '${alias}'. ` +
+                `Exported: ${[...exported].join(", ") || "(none)"}.`,
+            );
+          }
+          return;
+        }
+        if (instances.has(name)) return;
+        const suggestion = nearestName(name, [...instances]);
+        report(
+          "EXPORT_RESOURCE_UNKNOWN",
+          path,
+          `'exports.resources: ${name}' names no resource declared in this library. ` +
+            `Declared: ${[...instances].join(", ") || "(none)"}.` +
+            (suggestion ? ` Did you mean '${suggestion}'?` : ""),
+          suggestion,
+        );
+      });
+    }
+  }
+
+  return out;
+}

package/src/validate-extends.ts

@@ -4,6 +4,7 @@ import type { DefinitionRegistry } from "./definition-registry.js";
 import {
   controllerBearingAncestor,
   effectiveAuthorSchema,
+  hasOwnControllerOrTemplate,
   inheritedCapability,
   isInheritedDelegation,
   type DefResolver,
@@ -74,6 +75,44 @@ export function validateExtends(
     const resource = { kind: m.kind, name };
     const label = `${m.kind}/${name}`;
 
+    // `base:` is read on exactly one path — the inherited-controller one, which
+    // the kernel takes only when the definition has NO body of its own. A
+    // `resources:` block or a dispatch slot selects the template path, and
+    // `base:` is then never evaluated: the kind silently became an empty
+    // template, and the failure landed in the CONSUMER's resource as a `{}`
+    // where a parent instance should have been. Refused here, where the two
+    // blocks sit side by side, and at registration in the kernel.
+    //
+    // WHETHER there is a body is `hasOwnControllerOrTemplate` — the same
+    // predicate the kernel branches on, so the two halves cannot disagree about
+    // what a body is. Deciding it here with a key scan did disagree: an empty
+    // `resources: []` is falsy to a length test and truthy to the kernel's, so
+    // it passed `telo check` and threw `ERR_BASE_WITH_TEMPLATE_BODY` at boot —
+    // a brand-new guard shipping with the very gap it was written to close. The
+    // scan survives for one job only: naming the offending key in the message.
+    if ((m as { base?: unknown }).base != null) {
+      const hasBody = hasOwnControllerOrTemplate(m as ResourceDefinition);
+      const bodyKey =
+        (["resources", "controllers", "invoke", "run", "provide", "mount"] as const).find(
+          (key) => (m as Record<string, unknown>)[key] !== undefined,
+        ) ?? "resources";
+      if (hasBody) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "BASE_WITH_TEMPLATE_BODY",
+          source: SOURCE,
+          message:
+            `${label}: 'base:' maps this kind's config onto the inherited controller of ` +
+            `'${typeof extendsOf(m) === "string" ? extendsOf(m) : "<no extends>"}', so the ` +
+            `definition may not also declare '${bodyKey}:'. With '${bodyKey}:' the kind is a ` +
+            `template and 'base:' is never evaluated. Either drop 'base:' and dispatch to a ` +
+            `'resources:' entry with '!ref', or drop '${bodyKey}:' and build the parent's config ` +
+            `in 'base:' alone.`,
+          data: { resource, filePath, path: bodyKey },
+        });
+      }
+    }
+
     // --- extends validation ---
     // At this point `m.extends` is whatever the manifest declared (alias form, e.g.
     // "Ai.Model"). Resolve through the AliasResolver to the canonical form before
@@ -243,3 +282,7 @@ export function validateExtends(
 
   return diagnostics;
 }
+
+function extendsOf(m: ResourceManifest): unknown {
+  return (m as { extends?: unknown }).extends;
+}

package/src/validate-module-artifact.ts

@@ -4,6 +4,7 @@ import { parseLayerIndex, LayerIndexError } from "./artifact-layer-index.js";
 import {
   ArtifactSelectorError,
   PLATFORM_AXES,
+  selectorContradictions,
   selectorFromQualifiers,
   selectorKey,
 } from "./artifact-selector.js";
@@ -26,10 +27,12 @@ const SOURCE = "telo-analyzer";
  * selector (spec §1), which is what every module with two `js` controllers relies
  * on.
  *
- * 1. **Controller selector qualifiers.** `os` / `arch` / `libc` / `siblings` are
+ * 1. **Controller selector qualifiers.** The platform axes and `siblings` are
  *    authored surface. An unknown qualifier is reported rather than ignored, since
  *    ignoring is what makes a typo invisible; an invalid value is reported here
- *    instead of throwing from the loader later.
+ *    instead of throwing from the loader later, and so is a combination no host
+ *    can match (`selectorContradictions`, shared with `native:` and
+ *    `exports.code:`).
  * 2. **The published layer index.** The owner doc's JSON Schema covers shape; the
  *    semantic rules — controller-requires-selector, singletons carry none, no
  *    duplicate selector, the token grammar (`os: Linux` passes the schema and
@@ -79,6 +82,16 @@ function validateLibraryCandidates(manifest: ResourceManifest, out: AnalysisDiag
   // mean a consumer's import resolves by whichever candidate is read first.
   const seen = new Map<string, LibraryCandidate>();
   for (const candidate of candidates) {
+    for (const contradiction of selectorContradictions(candidate.selector)) {
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: `LIBRARY_${contradiction.rule}`,
+        source: SOURCE,
+        message:
+          `Telo.Library/${metadata?.name ?? "(unnamed)"}: ${candidate.origin}: ${contradiction.detail}`,
+        data: { resource, filePath: metadata?.source, path: "exports/code" },
+      });
+    }
     const key = selectorKey(candidate.selector);
     const first = seen.get(key);
     if (first) {
@@ -162,7 +175,37 @@ function validateControllerSelectors(
     // Validate the selector; the value is not otherwise needed here, since
     // candidates sharing a selector legitimately share a layer.
     try {
-      selectorFromQualifiers(parsed.format, parsed.qualifiers, candidate);
+      const selector = selectorFromQualifiers(parsed.format, parsed.qualifiers, candidate);
+      for (const contradiction of selectorContradictions(selector)) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: `CONTROLLER_${contradiction.rule}`,
+          source: SOURCE,
+          message:
+            `${manifest.kind}/${name ?? "(unnamed)"}: controller candidate "${candidate}": ` +
+            contradiction.detail,
+          data: { resource, filePath, path: `${at}?${contradiction.axis}` },
+        });
+      }
+      // A `dylib` opens over the Rust controller ABI, and a library built
+      // against another version of it must never match — so the candidate states
+      // which, in the `telo` family.
+      if (parsed.format === "dylib" && !selector.abi?.startsWith("telo-")) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "CONTROLLER_DYLIB_ABI_MISSING",
+          source: SOURCE,
+          message:
+            `${manifest.kind}/${name ?? "(unnamed)"}: dylib candidate "${candidate}" ` +
+            (selector.abi === undefined
+              ? `states no abi. `
+              : `states abi=${selector.abi}, which is not a Rust controller ABI. `) +
+            `A dylib is built against one version of the Rust controller ABI and must say which — ` +
+            `add abi=telo-<version>, e.g. abi=telo-2. Without it the Rust kernel downloads the ` +
+            `library on every host and refuses it only when it opens it.`,
+          data: { resource, filePath, path: at },
+        });
+      }
     } catch (err) {
       if (!(err instanceof ArtifactSelectorError)) throw err;
       out.push({

package/src/validate-native-entries.ts

@@ -0,0 +1,147 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+import { describeSelector, selectorContradictions, selectorKey } from "./artifact-selector.js";
+import { moduleDocumentClaims } from "./module-file-claims.js";
+import { describeClaim, nativeClaimConflicts } from "./module-named-files.js";
+import { readNativeEntries, type NativeEntry } from "./native-entries.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * The strict half of `native-entries.ts`: what `telo check` reports about a
+ * module doc's `native:` block.
+ *
+ * Every rule is decidable from the manifest and would otherwise surface only on
+ * a consumer's host, as a native file that never matches or a layer that
+ * overwrites another's file. Shape errors (a missing key, an unknown one) are
+ * left to the owner doc's JSON Schema, which reports them in the same pass.
+ *
+ * Entry-module-scoped: a dependency's block is not the consumer's to fix.
+ */
+export function validateNativeEntries(
+  manifests: ResourceManifest[],
+  entryModules?: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  for (const manifest of manifests) {
+    if (manifest.kind !== "Telo.Application" && manifest.kind !== "Telo.Library") continue;
+    const metadata = (manifest.metadata ?? {}) as Record<string, unknown>;
+    const name = typeof metadata.name === "string" ? metadata.name : undefined;
+    const owned =
+      entryModules === undefined ||
+      (typeof metadata.module === "string"
+        ? entryModules.has(metadata.module)
+        : name === undefined || entryModules.has(name));
+    if (!owned) continue;
+
+    const label = `${manifest.kind}/${name ?? "(unnamed)"}`;
+    const report = (code: string, path: string, message: string) =>
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code,
+        source: SOURCE,
+        message: `${label}: ${message}`,
+        data: {
+          resource: { kind: manifest.kind, name },
+          filePath: typeof metadata.source === "string" ? metadata.source : undefined,
+          path,
+        },
+      });
+
+    const { entries, problems } = readNativeEntries(manifest);
+    for (const problem of problems) {
+      if (problem.kind === "shape") continue;
+      report(
+        problem.kind === "escape" ? "NATIVE_PATH_ESCAPES_MODULE" : "NATIVE_ENTRY_INVALID",
+        problem.path,
+        problem.message,
+      );
+    }
+    if (entries.length === 0) continue;
+
+    const moduleName = typeof metadata.module === "string" ? metadata.module : name;
+    for (const { entry, claim } of nativeClaimConflicts(
+      entries,
+      moduleDocumentClaims(manifests, moduleName),
+    )) {
+      report(
+        "NATIVE_PATH_CLAIMED",
+        `native[${entry.index}].path`,
+        `${entry.origin}: path '${entry.path}' is also named by ${describeClaim(claim)}. A native ` +
+          `file ships only in its platform's native layer and a file extracts from exactly one ` +
+          `layer, so publish refuses it — give the native entry its own file, or drop the other ` +
+          `declaration.`,
+      );
+    }
+
+    const bySelector = new Map<string, NativeEntry>();
+    const byPath = new Map<string, NativeEntry>();
+    for (const entry of entries) {
+      const at = `native[${entry.index}]`;
+      if (entry.selector.format === "node" && entry.selector.abi === undefined) {
+        report(
+          "NATIVE_NODE_ABI_MISSING",
+          at,
+          `${entry.origin}: a 'node' addon is built against one Node ABI and must state it — ` +
+            `add abi: node-<NODE_MODULE_VERSION>, e.g. 'node-137'. Without it the file matches ` +
+            `every Node release and fails to load on all but one.`,
+        );
+      }
+      for (const contradiction of selectorContradictions(entry.selector)) {
+        report(
+          `NATIVE_${contradiction.rule}`,
+          `${at}.${contradiction.axis}`,
+          `${entry.origin}: ${contradiction.detail}`,
+        );
+      }
+
+      const key = `${entry.name}\0${selectorKey(entry.selector)}`;
+      const twin = bySelector.get(key);
+      if (twin) {
+        report(
+          "NATIVE_ENTRY_DUPLICATE",
+          at,
+          `${entry.origin}: ${twin.origin} already declares '${entry.name}' for ` +
+            `${describeSelector(entry.selector)}. A name has one entry per platform tuple, or ` +
+            `a lookup by name could resolve to either file.`,
+        );
+      } else {
+        bySelector.set(key, entry);
+      }
+
+      const sharer = byPath.get(entry.path);
+      if (sharer && selectorKey(sharer.selector) !== selectorKey(entry.selector)) {
+        report(
+          "NATIVE_PATH_SHARED",
+          `${at}.path`,
+          `${entry.origin}: path '${entry.path}' is also declared by ${sharer.origin} for ` +
+            `${describeSelector(sharer.selector)}. Every layer of a module extracts into one ` +
+            `directory, so each platform tuple needs its own path — e.g. ` +
+            `'native/<os>-<arch>/…'.`,
+        );
+      } else if (!sharer) {
+        byPath.set(entry.path, entry);
+      }
+
+      const through = [...byPath.values()].find(
+        (other) =>
+          other !== entry &&
+          (entry.path.startsWith(`${other.path}/`) || other.path.startsWith(`${entry.path}/`)),
+      );
+      if (through) {
+        const relation = entry.path.startsWith(`${through.path}/`)
+          ? `runs through '${through.path}' as a directory`
+          : `is a directory that '${through.path}' runs through`;
+        report(
+          "NATIVE_PATH_NESTED",
+          `${at}.path`,
+          `${entry.origin}: path '${entry.path}' ${relation}, and ${through.origin} declares ` +
+            `'${through.path}'. Every layer of a module extracts into one directory, so a path ` +
+            `cannot be both a file and a directory — give each entry its own path.`,
+        );
+      }
+    }
+  }
+  return out;
+}