@telorun/analyzer 0.72.0 → 0.74.0

package/src/eval-paths.ts

@@ -186,6 +186,36 @@ export function celEvalSites(schema: Record<string, any> | undefined): CelEvalSi
   return { compile, runtime, regions: extractCelRegionScopes(schema) };
 }
 
+/**
+ * A BASE-FORM CHILD'S OWN FIELDS ARE COMPILE-EVAL WITHOUT ANNOTATION.
+ *
+ * A definition with `base:` has no controller of its own: the kernel evaluates
+ * the mapping once, at `create()`, against `self` — the instance's config — and
+ * hands the result to the inherited controller as the parent's config. The
+ * child's own schema fields never reach a controller; they exist to be read by
+ * `base:`, and the mapping expands whatever compiled value it reads. So every
+ * own field is evaluated exactly once at creation against the startup scope,
+ * which is what compile-eval IS. Declared here as the rule rather than left as a
+ * property of the mapping walk — the `Telo.Provider` posture, where a
+ * construction-time-only surface declares compile-eval once for all its fields
+ * rather than per field. Without it the rule was off for every inheritance kind
+ * (its capability is inherited, so the gate read `undefined`) and the
+ * expressions were never typed either: a `!cel "variables.whoo"` passed `telo
+ * check` and failed at boot.
+ *
+ * Read by the kernel's instance production and the analyzer's coverage decision,
+ * so the two cannot disagree about which fields a base child evaluates. An
+ * explicitly `runtime` own field still wins, through the same overlap rule a
+ * root `x-telo-eval: compile` follows.
+ */
+export const IMPLICIT_COMPILE_SITES: CelEvalSites = { compile: ["**"], runtime: [], regions: [] };
+
+export function implicitEvalSites(
+  definition: { base?: unknown } | undefined,
+): CelEvalSites {
+  return definition?.base != null ? IMPLICIT_COMPILE_SITES : NO_CEL_EVAL_SITES;
+}
+
 /** The union of several schemas' sites — a kind's own and its capability
  *  abstract's, which is how a `Telo.Provider`'s implicit compile-eval reaches
  *  fields the provider never annotated. */
@@ -201,11 +231,16 @@ export function mergeCelEvalSites(...sites: CelEvalSites[]): CelEvalSites {
  * Whether the value at `path` is evaluated, and when — null for a field whose
  * value is read as a literal.
  *
- * `compile` wins over `runtime`, and both win over a region: a field's own
- * annotation is more specific than the region it sits in, which is the same
- * precedence a nested annotation has over an enclosing one. A region resolves to
- * `runtime` because that is what a region IS — a per-invocation scope naming
- * what its expressions can read.
+ * An annotated field wins over the region it sits in — a field's own annotation
+ * is more specific than an enclosing one, and a region resolves to `runtime`
+ * because that is what a region IS, a per-invocation scope naming what its
+ * expressions can read. Between the two annotations, `runtime` wins wherever
+ * they OVERLAP and `compile` answers everywhere else.
+ *
+ * That overlap rule is the kernel's, read back: its compile expansion skips any
+ * compile path a runtime path contains or is contained by, and under a root
+ * `**` it skips per top-level key — so a runtime-annotated field under an
+ * implicit compile root stays runtime, here as at dispatch.
  *
  * `path` is the `walkCelExpressions` spelling (`routes[0].returns[1].when`).
  */
@@ -213,8 +248,20 @@ export function celEvalModeAt(
   sites: CelEvalSites,
   path: string,
 ): "compile" | "runtime" | null {
-  if (evalPathsCover(sites.compile, path)) return "compile";
+  const compiled = sites.compile.some((p) => {
+    if (!evalPathCovers(p, path)) return false;
+    const effective = p === "**" ? topLevelKey(path) : p;
+    return !sites.runtime.some(
+      (rp) => evalPathCovers(rp, effective) || evalPathCovers(effective, rp),
+    );
+  });
+  if (compiled) return "compile";
   if (evalPathsCover(sites.runtime, path)) return "runtime";
   if (sites.regions.some((scope) => pathMatchesScope(path, scope))) return "runtime";
   return null;
 }
+
+function topLevelKey(path: string): string {
+  const end = path.search(/[.[]/);
+  return end === -1 ? path : path.slice(0, end);
+}

package/src/extends-resolution.ts

@@ -137,6 +137,30 @@ export function effectiveAuthorSchema(
   return mergeTypeSchemas([parentSchema, own]) as Record<string, any>;
 }
 
+/**
+ * The parent's required fields that a merge-form child leaves on its OWN author
+ * surface — inherited by the rule above, and not redeclared by the child.
+ *
+ * The one fact behind a confusing diagnostic: a kind written to wire a field
+ * internally still demands it from its consumer, because without `base:` the
+ * child is authored against merge(parent, own) and the parent's `required` comes
+ * along. Empty for a child with `base:` (its surface is its own schema) and for
+ * a kind that extends nothing, so a caller can use a non-empty result as the
+ * condition itself.
+ */
+export function inheritedRequiredFields(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): string[] {
+  if (!body(def).extends || body(def).base) return [];
+  const parent = resolveParent(def, resolve);
+  if (!parent) return [];
+  const required = effectiveAuthorSchema(parent, resolve).required;
+  if (!Array.isArray(required)) return [];
+  const own = ((body(def).schema ?? {}).properties ?? {}) as Record<string, unknown>;
+  return required.filter((f): f is string => typeof f === "string" && !(f in own));
+}
+
 /**
  * The fields a merge-form inheriting child publishes over its parent's reading.
  *

package/src/forwarded-declaration.ts

@@ -0,0 +1,32 @@
+/**
+ * Is this manifest, in a consumer's flattened analysis, a DEPENDENCY's code?
+ *
+ * Two stamps say so, and they are kept apart on purpose:
+ *
+ *  - `forwardedExport` — an imported library's exported instance, stamped by
+ *    flatten. It is what the consumer can reach, so the passes that count
+ *    EXPORTS (`validate-exports`, the `resources.<Alias>.<name>` index, zone
+ *    export seeding) read it and nothing else.
+ *  - `forwardedInternal` — a declaration inline extraction pulled OUT of a
+ *    forwarded manifest (a step target, an inline handler), stamped by
+ *    `normalizeInlineResources`. It is the library's code, written in the
+ *    library's names, and not something the library exports; counting it as an
+ *    export would let a consumer's `!ref Alias.<generated name>` pass a check the
+ *    kernel refuses.
+ *
+ * Every pass that asks "is this the consumer's to check, or to resolve its own
+ * names against?" asks THIS, so a dependency's extraction is treated exactly as
+ * the manifest it came out of.
+ *
+ * Browser-safe.
+ */
+export function isForwardedDeclaration(manifest: unknown): boolean {
+  const meta = (manifest as { metadata?: Record<string, unknown> } | undefined)?.metadata;
+  return meta?.forwardedExport === true || meta?.forwardedInternal === true;
+}
+
+/** Only an exported instance — for the passes that count what a library exports. */
+export function isForwardedExport(manifest: unknown): boolean {
+  const meta = (manifest as { metadata?: Record<string, unknown> } | undefined)?.metadata;
+  return meta?.forwardedExport === true;
+}

package/src/index.ts

@@ -33,6 +33,7 @@ export {
   celEvalSites,
   declaresCelRegion,
   evalPathCovers,
+  implicitEvalSites,
   mergeCelEvalSites,
   pathMatchesScope,
   NO_CEL_EVAL_SITES,
@@ -440,20 +441,37 @@ export {
   ArtifactSelectorError,
   describeSelector,
   isLayerRole,
+  normalizeAxisValue,
   normalizeSelector,
   roleCarriesSelector,
+  selectorContradictions,
   selectorFromQualifiers,
   selectorKey,
   selectorMatches,
+  undeterminedAxesBlockingMatch,
 } from "./artifact-selector.js";
 export type {
   ArtifactSelector,
   LayerRole,
   PlatformAxis,
   PlatformTarget,
+  SelectorContradiction,
 } from "./artifact-selector.js";
 export { collectModuleFileClaims } from "./module-file-claims.js";
-export type { ModuleFileClaim } from "./module-file-claims.js";
+export type { LocatedClaim, ModuleFileClaim } from "./module-file-claims.js";
+export {
+  crossLayerSourceLinks,
+  describeClaim,
+  nativeClaimConflicts,
+  stageableFiles,
+  unclaimedSourceEntries,
+} from "./module-named-files.js";
+export type {
+  CrossLayerLink,
+  LocatedSourceEntry,
+  NativeClaimConflict,
+  StageableFile,
+} from "./module-named-files.js";
 export { readLibraryCandidates } from "./module-library.js";
 export type {
   LibraryCandidate,
@@ -469,6 +487,24 @@ export {
 } from "./artifact-layer-index.js";
 export type { ArtifactLayer } from "./artifact-layer-index.js";
 export { validateModuleArtifact } from "./validate-module-artifact.js";
+export { normalizeNativePath, readNativeEntries } from "./native-entries.js";
+export type { NativeEntries, NativeEntry, NativeEntryProblem } from "./native-entries.js";
+export {
+  SOURCE_ARCHIVE_FORMATS,
+  readModuleSources,
+  resolveSourceUrl,
+  sourceUrlProblem,
+} from "./source-entries.js";
+export type {
+  ModuleSource,
+  ModuleSources,
+  SourceArchiveFormat,
+  SourceBuild,
+  SourceEntry,
+  SourcePin,
+  SourceProblem,
+  SourceProblemCode,
+} from "./source-entries.js";
 // Warnings everywhere, fatal at `telo publish` — descriptive metadata has no
 // runtime failure mode, so it must not stop a manifest running, but it is the
 // module's public face the moment it is published.

package/src/kernel-globals.ts

@@ -1,4 +1,5 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
 import { moduleMetadataSchema } from "./module-metadata-scope.js";
 import { residualEntrySchemaMap } from "./residual-schema.js";
 import { applyObservedStateNode } from "./validate-observed-state.js";
@@ -73,7 +74,10 @@ export function buildKernelGlobalsIndex(
       | Record<string, any>
       | undefined);
 
-  const entrySchema = globalsSchema(entryDoc, buildResourcesSchema(manifests, resources));
+  const entrySchema = globalsSchema(
+    entryDoc,
+    buildResourcesSchema(manifests, resources, entryDoc?.metadata?.name as string | undefined),
+  );
   const openResources = { type: "object", additionalProperties: true };
   const byModule = new Map<string, Record<string, any>>();
 
@@ -129,15 +133,34 @@ function buildModuleSchema(doc: ModuleGlobals | Record<string, any> | undefined)
   );
 }
 
-/** Every non-system resource name in the set, plus the scope-declared ones. */
+/** Every non-system resource name the entry module declares, plus the
+ *  scope-declared ones. */
 function buildResourcesSchema(
   manifests: ResourceManifest[],
-  resources?: ReadonlyMap<string, { kind: string; status?: Record<string, any> }>,
+  resources:
+    | ReadonlyMap<string, { kind: string; status?: Record<string, any>; forwardedFrom?: string }>
+    | undefined,
+  entryModule: string | undefined,
 ): Record<string, any> {
   const resourceProps: Record<string, any> = {};
   for (const m of manifests) {
     const name = m.metadata?.name as string | undefined;
     if (!name || !m.kind) continue;
+    // A dependency's code is not in the consumer's `resources`: an export is read
+    // as `resources.<Alias>.<name>`, and what extraction pulled out of one is
+    // reachable under no name at all.
+    if (isForwardedDeclaration(m)) continue;
+    // Nor are the imports a dependency declares for itself: its aliases publish
+    // into its own module's `resources`.
+    const module = m.metadata?.module;
+    if (
+      m.kind === "Telo.Import" &&
+      entryModule !== undefined &&
+      typeof module === "string" &&
+      module !== entryModule
+    ) {
+      continue;
+    }
     // Telo.Import snapshots are stored under resources.<alias> at runtime,
     // so they appear here alongside regular resources.
     if (!SYSTEM_KINDS.has(m.kind)) {
@@ -148,14 +171,14 @@ function buildResourcesSchema(
   // now, so their names resolve too — inside the scope's regions, which is where
   // the only expressions that can name them live.
   for (const [key, entry] of resources ?? []) {
-    if (key.includes(".")) continue;
+    if (key.includes(".") || entry.forwardedFrom !== undefined) continue;
     resourceProps[key] ??= { type: "object", additionalProperties: true };
     if (entry.status) applyObservedStateNode(resourceProps, key, entry.status);
   }
   // Imports' exported instances publish two levels deep (`resources.<Alias>.<name>`);
   // the alias node stays open so its other keys keep resolving.
   for (const [key, entry] of resources ?? []) {
-    if (!key.includes(".") || !entry.status) continue;
+    if (!key.includes(".") || !entry.status || entry.forwardedFrom !== undefined) continue;
     applyObservedStateNode(resourceProps, key, entry.status);
   }
 

package/src/migrations/CLAUDE.md

@@ -0,0 +1,35 @@
+# Manifest migrations — guide
+
+Loaded when working under `analyzer/nodejs/src/migrations/`. Author guide: `docs/extend/manifest-migrations.md`. The entries themselves are data under `analyzer/migrations/`.
+
+**A migration is a legacy spelling rewritten to the current one, because published artifacts carry the old and cannot be edited.** Distinct from a **normalization** (`desugarImports`, `normalizeInlineResources`, `resolveRefSentinels`, `resolveSchemaRefKinds`, `rewriteSyntheticOrigins`), which folds authoring sugar into the internal form and is correctly invisible. One "rewrite pass" abstraction covering both was rejected: it would carry a "reported / written back" flag on every entry, putting desugaring one boolean away from editing a user's manifest. Registry + driver in `analyzer/nodejs/src/migrations/`; author guide in `docs/extend/manifest-migrations.md`.
+
+**An entry is DATA in both halves and contains no code** — one JSON file per entry under `analyzer/migrations/`, read as one lexically ordered set. A predicate expressed in one language would be readable by one kernel only, which is the divergence the design exists to prevent. JSON rather than YAML because it is the only format all three runtimes embed with no generation step: Rust has `include_str!`, Go has `//go:embed`, TypeScript has neither and only `resolveJsonModule`. The files sit beside the language implementations rather than inside either; `scripts/copy-migration-entries.mjs` (the analyzer's `prepare`) copies them in and emits the barrel from the same directory listing, so a file that exists always runs — a hand-maintained list was the one place the mechanism could fail silently.
+
+**The patch names what it TARGETS** — `rename-key`, `set-value`, `set-tag`, `insert-item`, `remove-entry`, each with one fixed parameter shape and no path of its own. **Every operation has a known YAML edit form**: that is what makes a migration applicable to a *file* at all, and what lets the driver **derive** whether a quick fix exists — read straight off the verb, never declared, so a missing repair is stated rather than silent. A written `value` must be a **scalar**, refused at entry-READ time: the file applier re-quotes a value in the author's style at the node's own span, which has no meaning for a mapping, so accepting one would make the limitation invisible until a user ran `telo migrate` and was told, permanently, to fix it by hand. The model is JSON Patch's; the *names* deliberately are not, because these are narrower and a lookalike wearing a standard's names invites expectations it does not meet (`move` relocates across parents and replaces an occupied destination; `rename-key` renames within one mapping and *refuses* one).
+
+**A SCHEMA REGION is the one containment a kind list cannot express.** An annotation keyword occurs in author-written JSON Schema, and schema fragments are not confined to kind documents: an inline `inputType:` / `outputType:` on any kind that declares one, an API route's `request.schema.body`, a `Telo.JsonSchema`'s `schema`. That set of kinds is open, and enumerating the standard library's would put resource-kind knowledge into the analyzer. So `inSchema: true` bounds a rule to nodes reached through the **kernel's own** schema-valued keys (`schema`, `status`, `inputType`, `outputType`, `itemType`), which no kind owns — and only with it may `inKind` / `under` be `["*"]`, and only for a rule whose `key` begins with `x-telo-`, both refused at entry-read. That pairing is the containment: the region bounds where the walk may go, the reserved key bounds what it may touch. The wildcard drops the bounded walk, which is not worth pricing at Telo's scale; what it genuinely costs is one wrong-rewrite residue — a schema literal inside an assertion's expected value, rewritten into its own synonym — which cannot be closed in a data-only matcher without naming kinds, and is accepted because the sites it reaches are exactly the ones no enumeration covers.
+
+**The matcher's containment is POSITIVE and required** (`analyzer/nodejs/src/migrations/match.ts`): `inKind` names the document kinds a rule may touch, `under` the region within them it may reach, and nothing outside is reachable; `value`/`valueOneOf`, `withSibling` and `notUnder` narrow within it. **`under` is ANCHORED at the document root** — it names top-level keys and the match must be at or below one of them, which is what makes the containment claim true rather than decorative: a `Telo.Definition`'s `resources:` template body carries other kinds' configuration, so a rule matching "any path segment spelled `schema`" would reach the very user JSON blob the positive form exists to keep out, and delete from it silently. Both gates bound the WALK rather than filter its output (`applicableRules` → `buildMatchIndex`), so a document no rule targets is never walked and a region no rule names is never descended into — this runs on the kernel's boot path for every file in the graph, and `type:` alone occurs a couple of hundred times in a standard-library manifest. Walk-everything-and-subtract cannot be made sound — the set to subtract is unbounded, since any kind whose config carries a user JSON blob can hold something shaped like the node a rule looks for — and it cannot express the guarantee the module surface is promised to carry (*a dependency renames its own field and provably nothing else*), which is a statement about what a rule may REACH and so has to be said positively. Both halves are closed vocabularies and an unknown token is refused, never ignored. A migration that does not fit is a signal to extend the vocabulary, never to hand-write a rewrite.
+
+**One phase, in the loader (`parseLoadedFile`), after parse and before both `precompileDoc` and `desugarLoadedFile`.** The driver invariant is that **a migration only ever matches author-written nodes**, and the position is what makes that structural rather than a convention: a synthetic `Telo.Import` has no YAML document to edit, would record a path the file never had, and shares `variables`/`secrets` *by reference* with the module doc, so a match inside one would apply twice. Before precompile for the same reason in miniature — a matcher must see what the author wrote, not a `CompiledValue`. **No post-resolution phase**: it would sit inside the analyze pass, which the Rust side does not have, so every entry in it would be structurally Node-only — reintroducing the divergence the design exists to prevent.
+
+**Composition is the driver's guarantee, not each entry's proof obligation.** One pass, match set frozen against the pre-migration tree (so no rule matches a node another rule produced), rules ordered within an entry, entries independent — which is cross-party determinism once module entries are aggregated. Idempotency then follows from the driver: a rule matches only the legacy spelling, so re-running finds nothing. **A migration that cannot rewrite leaves the node untouched** (a malformed value, an occupied `rename-key` destination) for the ordinary validator to reject — never guessing, never dropping. Freezing is not enough for a **sequence index**, which is not an identity: a stale KEY path resolves to nothing and refuses itself, while a stale index silently names a different element, so the driver tracks which arrays a patch resized and refuses any later indexed match into one. The file applier is stricter in one further way — two patches whose byte spans overlap cannot both splice, so the later is dropped — and, unlike the tree, it **reports** what it could not write (`migrateFileText`'s `unwritable`), because the diagnostic that sent the author to `telo migrate` would otherwise leave a warning with no way to act on it. **A removal of a mapping entry that OPENS a sequence item splices to the following key** rather than deleting the line (which would take the `- ` with it and fold the item into its predecessor): a legacy ref slot is overwhelmingly an `anyOf` branch written `- type: string`, so refusing it would have made the diagnostic's own advice dead for the case it is most often given in. **The scalar re-quoting rule and the splice loop are ONE primitive** (`analyzer/nodejs/src/yaml-source-edit.ts`, browser-safe), read by the migration applier, `ide-support`'s quick fix and `telo upgrade`'s pin rewrite alike — three surfaces write repairs into the same files, and two copies of a subtle quoting rule would eventually quote one value two ways with nothing to catch it.
+
+**Rewrite always, report locally.** The runtime must read artifacts published years ago, so every file in the graph is rewritten; only the ENTRY module's own files (owner + `include:` partials) report, because a published dependency is not the consumer's to fix. Enforced at `loadGraph` (`LoadedGraph.migrationDiagnostics`), while the per-file record lives on `LoadedFile.migrations`. **Path provenance is part of the contract**: each rewrite records `legacyPath` beside `migratedPath`, `remapMigratedPaths` maps every downstream diagnostic back before position resolution (`assembleGraphDiagnostics`, the editor's closure, and the SDK's `check` seam — all three, since a caller acts on `path` and one surface reporting the migrated spelling would make a manifest mean two things depending on who asked), and `telo migrate` reads its edit target from the same record — the generalization of `rewriteSyntheticOrigins`. Without it a key rename silently downgrades every squiggle on that node to a parent, and a fix among them writes across a parent's span. **The general index is by FILE and every rewrite is in it** — a diagnostic carries at most two routing facts and routinely only one, so indexing by resource identity alone left every diagnostic without `data.resource` and every rewrite in a doc without `metadata.name` (all of `Telo.Import`) simply unreachable. `(kind, name)` is the NARROWING index, never the general one: resource names are module-scoped, so two libraries declaring a `Store` would share one bucket and move each other's squiggles. Where narrowing is impossible — an identity declared in several files with no `filePath`, or two records in one file covering a path with different legacy spellings — nothing is remapped rather than guessed.
+
+**`LoadOptions.migrate` is a third cache axis** beside `compile` and `desugarImports` (variant tag `m`/`x`), opt-in like both. Every resolved consumer passes it; a **round-trip** view must not, since the editor pairs manifests to YAML nodes by index and writes the pair back on save, and `telo migrate` has to see the legacy spelling to find it. Forgetting it fails loudly (the old spelling reaches the validator), never silently.
+
+**A diagnostic composes in three parts and the entry writes only one.** The driver generates *what changed* and *how to apply it* identically for every entry; the entry supplies `reason` — a sentence or two of rationale, never a clause of the generated sentence, and entry-level because one entry may carry several rules that share one story. An entry also declares its stable `id`, `code` and `severity`. **No version stamp**: "can this be deleted?" turns on whether any published artifact still carries the spelling, which the hub can answer and a stamp cannot.
+
+**File application reuses byte-splice editing, not `Document.toString()`** (`migrations/yaml-edit.ts`) — the `cli/nodejs/src/commands/upgrade.ts` precedent: re-serializing re-folds block scalars, drops quote-style hints and reflows strings, so a one-key repair would land as a whole-file diff. The document is never mutated, so every effect of a patch resolves at the location the patch matched. **`telo migrate` is the REFERENCE application, not the only one** — applying pending migrations is an operation other commands compose over a subset of entries, and `telo upgrade` is the case that matters (it should repair what its pin move broke, over just the modules it moved). That composition waits on the module surface, since core-only entries have no per-module subset.
+
+**Two declaration surfaces, one mechanism** — a **core** entry ships with the analyzer and may name any `inKind`; a **module** entry ships in a module's artifact and may name only kinds that module owns. Scope of match and provenance differ, not shape; the closed vocabulary is the trust boundary. The module surface is planned separately, as is the Rust reader and `kernel/specs/manifest-migrations.md`.
+
+A second committed entry is **`normalize-value-types`**, which rewrites `x-telo-stream: true` / `x-telo-binary: true` to `x-telo-type: Telo.Stream` / `Telo.Bytes` and qualifies a bare `TcpPort` / `UdpPort` — the entry the schema region exists for, and the first to use the wildcard forms.
+
+The committed entry is **`ref-slot-scalar-type`**, which drops the scalar `type:` a reference slot pinned back when references were plain strings. It replaced `normalizeRefSlots`, which did the same rewrite at every schema-compile site regardless of `LoadOptions.migrate` — a duplicate with a *different* traversal, and one that falsified the design's own safety property, since a consumer who forgot the flag behaved identically apart from the missing warning. Deleting it is what makes the entry able to prove the mechanism it demonstrates.
+
+## Where to look
+
+- "an old spelling has to keep loading" → `analyzer/nodejs/src/migrations/` (`types.ts` the entry vocabulary, `patch.ts` the plan/apply split, `yaml-edit.ts` the file repair, `match.ts` the selector, `driver.ts` the guarantees, `report.ts` the diagnostic, `provenance.ts` the path remap, `registry.ts` the set), `cli/nodejs/src/commands/migrate.ts`

package/src/module-alias-scope.ts

@@ -60,6 +60,23 @@ export function moduleAliasScope<A extends KindResolver, M extends KindResolver>
   return aliasesByModule?.get(declaringModule) ?? aliases;
 }
 
+/**
+ * A manifest's kind, resolved to its definition in the alias table of the
+ * module that wrote it — the canonical spelling first, as every other lookup in
+ * the analyzer does (`resolve(resolveKind(k) ?? k)`), so an alias that happens to
+ * spell another module's canonical kind cannot win over the one it names.
+ */
+export function definitionInScope<D>(
+  registry: { resolve(kind: string): D | undefined },
+  kind: string,
+  metadata: { module?: unknown } | undefined,
+  aliases: KindResolver | undefined,
+  aliasesByModule: ReadonlyMap<string, KindResolver> | undefined,
+): D | undefined {
+  const canonical = moduleAliasScope(metadata, aliases, aliasesByModule)?.resolveKind(kind);
+  return (canonical ? registry.resolve(canonical) : undefined) ?? registry.resolve(kind);
+}
+
 /** All this rule needs of a resolver, and deliberately all it asks for:
  *  `ModuleScopes` already types its map this way so a caller can hand over a
  *  lighter table, and requiring the full `AliasResolver` here would have made

package/src/module-file-claims.ts

@@ -4,16 +4,22 @@ import {
   walkCelExpressions,
   type TemplatingEngineRegistry,
 } from "@telorun/templating";
+import type { ResourceManifest } from "@telorun/sdk";
 import { PackageURL } from "packageurl-js";
 import { parseAllDocuments } from "yaml";
-import { selectorFromQualifiers, selectorKey, type ArtifactSelector } from "./artifact-selector.js";
+import {
+  ArtifactSelectorError,
+  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
  * to.
  *
- * The single answer to "why is this file in the payload", replacing two
+ * The answer to "why is this file in the payload" for everything but `native:` entries (read by `native-entries.ts`), replacing two
  * derivations that happened to agree: publish used to re-parse the manifest with
  * PURL knowledge hardcoded into the CLI, and any second vocabulary — a tag that
  * embeds a file, say — would have had to be added there by hand. Here the
@@ -188,11 +194,64 @@ function claimKey(claim: ModuleFileClaim): string {
 export function collectModuleFileClaims(
   manifestText: string,
   registry: TemplatingEngineRegistry = defaultRegistry(),
+): ModuleFileClaim[] {
+  return collectDocumentFileClaims(
+    parseAllDocuments(manifestText, { customTags: defaultCustomTags() }).map(
+      (doc) => doc.toJSON() as unknown,
+    ),
+    registry,
+  );
+}
+
+/** A claim, with the document that made it when the caller knows which. */
+export interface LocatedClaim {
+  readonly claim: ModuleFileClaim;
+  /** `<kind>/<name>` of the declaring document. */
+  readonly where?: string;
+}
+
+/**
+ * The claims one module's own documents make, out of an analysis set that also
+ * holds its dependencies' documents. A document whose candidate selector cannot
+ * be read contributes none — `validateModuleArtifact` reports it.
+ */
+export function moduleDocumentClaims(
+  manifests: readonly ResourceManifest[],
+  moduleName: string | undefined,
+  registry: TemplatingEngineRegistry = defaultRegistry(),
+): LocatedClaim[] {
+  const out: LocatedClaim[] = [];
+  for (const doc of manifests) {
+    const metadata = (doc.metadata ?? {}) as Record<string, unknown>;
+    const docModule =
+      typeof metadata.module === "string"
+        ? metadata.module
+        : doc.kind === "Telo.Application" || doc.kind === "Telo.Library"
+          ? metadata.name
+          : undefined;
+    if (docModule !== moduleName) continue;
+    let claims: ModuleFileClaim[];
+    try {
+      claims = collectDocumentFileClaims([doc], registry);
+    } catch (err) {
+      if (err instanceof ArtifactSelectorError) continue;
+      throw err;
+    }
+    const where = `${doc.kind}/${typeof metadata.name === "string" ? metadata.name : "(unnamed)"}`;
+    for (const claim of claims) out.push({ claim, where });
+  }
+  return out;
+}
+
+/** The same claims, from one module's already-parsed documents — the form the
+ *  analysis pass holds. */
+export function collectDocumentFileClaims(
+  docs: readonly unknown[],
+  registry: TemplatingEngineRegistry = defaultRegistry(),
 ): ModuleFileClaim[] {
   const seen = new Set<string>();
   const claims: ModuleFileClaim[] = [];
-  for (const doc of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
-    const json = doc.toJSON() as unknown;
+  for (const json of docs) {
     for (const claim of [
       ...libraryClaims(json),
       ...controllerClaims(json),

package/src/module-named-files.ts

@@ -0,0 +1,162 @@
+/**
+ * The rules that relate a module's `native:` entries, its file claims and its
+ * `sources:` block — which files a source may stage, which declarations collide
+ * on one path, and which staged entries nothing names.
+ *
+ * One home, because `telo check` (`validate-native-entries.ts`,
+ * `validate-source-entries.ts`) and `telo publish` apply the same rules to the
+ * same manifest; two copies would each drift toward whatever its own tests pin.
+ * Callers read the three blocks with their own readers and hand the results in.
+ * Browser-safe: no filesystem.
+ */
+
+import { PLATFORM_AXES, describeSelector } from "./artifact-selector.js";
+import type { LocatedClaim, ModuleFileClaim } from "./module-file-claims.js";
+import type { NativeEntry } from "./native-entries.js";
+import type { ModuleSource, SourceEntry } from "./source-entries.js";
+
+const CLAIM_LABEL: Record<ModuleFileClaim["role"], string> = {
+  controller: "the controller candidate",
+  library: "the exports.code entry",
+  assets: "the embed",
+};
+
+/** The declaration behind a claim, for messages: `the controller candidate pkg:… on Telo.Definition/Reader`. */
+export function describeClaim(located: LocatedClaim): string {
+  const { claim, where } = located;
+  return `${CLAIM_LABEL[claim.role]} ${claim.origin}${where === undefined ? "" : ` on ${where}`}`;
+}
+
+/** A `native:` entry whose path another declaration also names. */
+export interface NativeClaimConflict {
+  readonly entry: NativeEntry;
+  readonly claim: LocatedClaim;
+}
+
+/**
+ * Every `native:` entry whose path the module also names as code or as an embed.
+ * Each declaration decides a different layer, and a file extracts from exactly
+ * one — a runtime materializing one would find the file missing through the other.
+ */
+export function nativeClaimConflicts(
+  native: readonly NativeEntry[],
+  claims: readonly LocatedClaim[],
+): NativeClaimConflict[] {
+  const out: NativeClaimConflict[] = [];
+  for (const entry of native) {
+    for (const claim of claims) {
+      if (claim.claim.path === entry.path) out.push({ entry, claim });
+    }
+  }
+  return out;
+}
+
+/** A file a `sources:` entry may stage. */
+export interface StageableFile {
+  readonly path: string;
+  /** The declaration naming it, for messages. */
+  readonly label: string;
+  /** The layer it ships in, for messages. */
+  readonly layer: string;
+  /** Produced by a controller build (`local_path=`) rather than staged or committed. */
+  readonly built: boolean;
+}
+
+/**
+ * The files the module names that a `sources:` entry may stage: every `native:`
+ * entry's path, and every bundled controller candidate's `path=` that carries a
+ * platform qualifier. A platform-neutral candidate is one bundle for every host,
+ * which nothing stages.
+ */
+export function stageableFiles(
+  native: readonly NativeEntry[],
+  claims: readonly LocatedClaim[],
+): Map<string, StageableFile> {
+  const out = new Map<string, StageableFile>();
+  for (const entry of native) {
+    if (out.has(entry.path)) continue;
+    out.set(entry.path, {
+      path: entry.path,
+      label: `${entry.origin} for ${describeSelector(entry.selector)}`,
+      layer: `native ${describeSelector(entry.selector)}`,
+      built: false,
+    });
+  }
+  for (const { claim } of claims) {
+    if (claim.role !== "controller") continue;
+    if (!PLATFORM_AXES.some((axis) => claim.selector[axis] !== undefined)) continue;
+    const existing = out.get(claim.path);
+    if (existing) {
+      if (claim.localPath && !existing.built) out.set(claim.path, { ...existing, built: true });
+      continue;
+    }
+    out.set(claim.path, {
+      path: claim.path,
+      label: `controller candidate ${claim.origin}`,
+      layer: `controller ${describeSelector(claim.selector)}`,
+      built: claim.localPath !== undefined,
+    });
+  }
+  return out;
+}
+
+/** A `sources:` entry, with the source declaring it. */
+export interface LocatedSourceEntry {
+  readonly source: ModuleSource;
+  readonly entry: SourceEntry;
+}
+
+/**
+ * The staged entries nothing in the module names: not a stageable file, and not
+ * one of the entry's own source's notices. `alsoNamed` holds paths the caller
+ * knows are named though they did not read — a `native:` entry with an unrelated
+ * problem — so one defect is not reported twice.
+ */
+export function unclaimedSourceEntries(
+  sources: readonly ModuleSource[],
+  stageable: ReadonlyMap<string, StageableFile>,
+  alsoNamed: ReadonlySet<string> = new Set(),
+): LocatedSourceEntry[] {
+  const out: LocatedSourceEntry[] = [];
+  for (const source of sources) {
+    for (const entry of source.entries) {
+      if (stageable.has(entry.path) || source.notices.includes(entry.path)) continue;
+      if (alsoNamed.has(entry.path)) continue;
+      out.push({ source, entry });
+    }
+  }
+  return out;
+}
+
+/** A link whose target ships in a different layer than the link. */
+export interface CrossLayerLink {
+  readonly source: ModuleSource;
+  readonly entry: Extract<SourceEntry, { kind: "link" }>;
+  readonly layer: string;
+  readonly targetLayer: string;
+}
+
+/**
+ * The link entries whose target ships in another layer. A runtime extracts only
+ * the layers it needs, so such a link dangles wherever the other layer is not
+ * materialized. A notice ships in `common`.
+ */
+export function crossLayerSourceLinks(
+  sources: readonly ModuleSource[],
+  stageable: ReadonlyMap<string, StageableFile>,
+): CrossLayerLink[] {
+  const layerOf = (source: ModuleSource, path: string): string | undefined =>
+    stageable.get(path)?.layer ?? (source.notices.includes(path) ? "common" : undefined);
+  const out: CrossLayerLink[] = [];
+  for (const source of sources) {
+    for (const entry of source.entries) {
+      if (entry.kind !== "link") continue;
+      const layer = layerOf(source, entry.path);
+      const targetLayer = layerOf(source, entry.resolved);
+      if (layer !== undefined && targetLayer !== undefined && layer !== targetLayer) {
+        out.push({ source, entry, layer, targetLayer });
+      }
+    }
+  }
+  return out;
+}