@telorun/analyzer 0.73.0 → 0.74.0

package/src/artifact-selector.ts

@@ -3,7 +3,8 @@
  * controller candidate is chosen by, and the key a controller layer of a module
  * artifact is stored under.
  *
- * A selector is `format` plus the optional platform axes `os` / `arch` / `libc`.
+ * A selector is `format` plus the optional platform axes, whose vocabulary is
+ * data (`analyzer/artifact-axes/axes.json`, generated into `PLATFORM_AXES`).
  * Matching is one rule, applied per axis: an axis the selector omits accepts
  * anything, an axis it states must be equal. That is what lets a `js` controller
  * be platform-neutral and a `napi` controller be pinned to one triple, with no
@@ -25,11 +26,20 @@
  * published into OCI descriptors.
  */
 
-/** The role a layer plays in a module artifact. `controller` and `library` layers
- *  carry a selector; `assets` and `common` are singletons and carry none. */
-export type LayerRole = "controller" | "library" | "assets" | "common";
+import { AXIS_VALUE_FORMS, PLATFORM_AXES, type PlatformAxis } from "./artifact-axes.js";
 
-export const LAYER_ROLES: readonly LayerRole[] = ["controller", "library", "assets", "common"];
+/** The role a layer plays in a module artifact. `controller`, `library` and
+ *  `native` layers carry a selector; `assets` and `common` are singletons and
+ *  carry none. */
+export type LayerRole = "controller" | "library" | "native" | "assets" | "common";
+
+export const LAYER_ROLES: readonly LayerRole[] = [
+  "controller",
+  "library",
+  "native",
+  "assets",
+  "common",
+];
 
 export function isLayerRole(value: unknown): value is LayerRole {
   return typeof value === "string" && (LAYER_ROLES as readonly string[]).includes(value);
@@ -42,33 +52,28 @@ export function isLayerRole(value: unknown): value is LayerRole {
  *  A singleton would be wrong the moment a second runtime ships. */
 export const CODE_LAYER_ROLES: readonly LayerRole[] = ["controller", "library"];
 
+/** Every role keyed by a selector, one layer per selector: the code roles, plus
+ *  `native` — a platform-specific file the runtime does not import as code,
+ *  declared in the module doc's `native:` block. */
+const SELECTOR_LAYER_ROLES: readonly LayerRole[] = [...CODE_LAYER_ROLES, "native"];
+
 export function roleCarriesSelector(role: LayerRole): boolean {
-  return (CODE_LAYER_ROLES as readonly string[]).includes(role);
+  return (SELECTOR_LAYER_ROLES as readonly string[]).includes(role);
 }
 
-/** The platform axes, in canonical order. Not a closed vocabulary of *values* —
- *  new architectures appear without a Telo release — only of axis names. */
-export const PLATFORM_AXES = ["os", "arch", "libc"] as const;
+export { PLATFORM_AXES, type PlatformAxis };
 
-export type PlatformAxis = (typeof PLATFORM_AXES)[number];
-
-export interface ArtifactSelector {
+export interface ArtifactSelector extends Partial<Record<PlatformAxis, string>> {
   /** Bundled controller format: the PURL name segment (`js`, `napi`, `wasm`, …). */
   format: string;
-  os?: string;
-  arch?: string;
-  libc?: string;
 }
 
 /** What a selector is matched against: the host the kernel runs on, or the
- *  target `telo install --platform` is warming a cache for. An axis left
- *  undetermined (a host whose libc cannot be detected) matches no selector that
- *  constrains it — refusing to load is the safe direction for a native binary. */
-export interface PlatformTarget {
+ *  target `telo install` is warming a cache for. An axis left undetermined (a
+ *  host whose libc cannot be detected) matches no selector that constrains it —
+ *  refusing to load is the safe direction for a native binary. */
+export interface PlatformTarget extends Partial<Record<PlatformAxis, string>> {
   format?: string;
-  os?: string;
-  arch?: string;
-  libc?: string;
 }
 
 export class ArtifactSelectorError extends Error {
@@ -84,7 +89,9 @@ export class ArtifactSelectorError extends Error {
  *  platform written two ways is one layer rather than two. */
 const TOKEN = /^[a-z0-9][a-z0-9_.-]*$/;
 
-function normalizeToken(axis: string, raw: unknown, describe: string): string {
+/** Validate and normalize one selector value: the shared token grammar, plus the
+ *  axis's own value form where the vocabulary declares one. */
+export function normalizeAxisValue(axis: string, raw: unknown, describe: string): string {
   if (typeof raw !== "string") {
     throw new ArtifactSelectorError(
       `${describe}: ${axis} must be a string, got ${raw === null ? "null" : typeof raw}.`,
@@ -97,6 +104,13 @@ function normalizeToken(axis: string, raw: unknown, describe: string): string {
         `Use lowercase letters, digits, '.', '-' or '_', starting with a letter or digit.`,
     );
   }
+  const valueForm = AXIS_VALUE_FORMS[axis as PlatformAxis];
+  if (valueForm && !valueForm.pattern.test(value)) {
+    throw new ArtifactSelectorError(
+      `${describe}: ${axis} value '${raw}' must have the form ${valueForm.form}, ` +
+        `e.g. ${valueForm.examples.map((e) => `'${e}'`).join(" or ")}.`,
+    );
+  }
   return value;
 }
 
@@ -111,35 +125,38 @@ export function selectorFromQualifiers(
   describe = "controller selector",
 ): ArtifactSelector {
   const selector: ArtifactSelector = {
-    format: normalizeToken("format", format, describe),
+    format: normalizeAxisValue("format", format, describe),
   };
   for (const axis of PLATFORM_AXES) {
     const raw = qualifiers?.[axis];
     if (raw === undefined || raw === "") continue;
-    selector[axis] = normalizeToken(axis, raw, describe);
+    selector[axis] = normalizeAxisValue(axis, raw, describe);
   }
   return selector;
 }
 
-/** Validate and normalize a selector read off a published layer index. */
+/**
+ * Validate and normalize a selector read off a published layer index.
+ *
+ * Returns undefined when the selector carries an axis this runtime does not
+ * know: the layer is for a newer runtime, and the caller skips it whole. The
+ * unknown axis is never dropped — two layers differing only in it would then
+ * claim one address. The known axes are still validated, since their grammar
+ * does not change with the axis set.
+ */
 export function normalizeSelector(
   value: unknown,
   describe = "layer selector",
-): ArtifactSelector {
+): ArtifactSelector | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new ArtifactSelectorError(`${describe}: expected an object of selector axes.`);
   }
   const record = value as Record<string, unknown>;
-  const unknown = Object.keys(record).filter(
+  const selector = selectorFromQualifiers(record.format, record, describe);
+  const carriesUnknownAxis = Object.keys(record).some(
     (k) => k !== "format" && !(PLATFORM_AXES as readonly string[]).includes(k),
   );
-  if (unknown.length > 0) {
-    throw new ArtifactSelectorError(
-      `${describe}: unknown selector ${unknown.length === 1 ? "axis" : "axes"} ` +
-        `${unknown.map((k) => `'${k}'`).join(", ")}. Known axes: format, ${PLATFORM_AXES.join(", ")}.`,
-    );
-  }
-  return selectorFromQualifiers(record.format, record, describe);
+  return carriesUnknownAxis ? undefined : selector;
 }
 
 /**
@@ -180,3 +197,61 @@ export function selectorMatches(selector: ArtifactSelector, target: PlatformTarg
   }
   return true;
 }
+
+/**
+ * The axes `selector` constrains and `target` leaves undetermined, when those
+ * alone keep the two from matching — what a warm skips for want of a value rather
+ * than because the selector is for another platform. `undefined` when the
+ * selector matches, or differs on a determined axis.
+ */
+export function undeterminedAxesBlockingMatch(
+  selector: ArtifactSelector,
+  target: PlatformTarget,
+): PlatformAxis[] | undefined {
+  if (target.format !== undefined && selector.format !== target.format) return undefined;
+  const axes: PlatformAxis[] = [];
+  for (const axis of PLATFORM_AXES) {
+    const constraint = selector[axis];
+    if (constraint === undefined) continue;
+    if (target[axis] === undefined) axes.push(axis);
+    else if (target[axis] !== constraint) return undefined;
+  }
+  return axes.length > 0 ? axes : undefined;
+}
+
+/** A selector that no host can match as its author meant it. */
+export interface SelectorContradiction {
+  /** Suffix of the diagnostic code; each surface prefixes its own. */
+  readonly rule: "NAPI_ABI_FORBIDDEN" | "LIBC_OFF_LINUX";
+  readonly axis: PlatformAxis;
+  readonly detail: string;
+}
+
+/**
+ * The combinations of axes the grammar accepts and no host can mean: an N-API
+ * addon stating a runtime ABI, and a libc on an os that has none. Shared by every
+ * surface that authors a selector — `native:` entries, controller candidates and
+ * `exports.code:` entries — so each reports the same rule under its own prefix.
+ */
+export function selectorContradictions(selector: ArtifactSelector): SelectorContradiction[] {
+  const out: SelectorContradiction[] = [];
+  if (selector.format === "napi" && selector.abi !== undefined) {
+    out.push({
+      rule: "NAPI_ABI_FORBIDDEN",
+      axis: "abi",
+      detail:
+        `an N-API addon is ABI-stable across runtime releases and states no abi — remove ` +
+        `abi ${selector.abi}, which would keep it from loading anywhere else.`,
+    });
+  }
+  if (selector.libc !== undefined && selector.os !== undefined && selector.os !== "linux") {
+    out.push({
+      rule: "LIBC_OFF_LINUX",
+      axis: "libc",
+      detail:
+        `libc is only determined on linux, so a selector for os '${selector.os}' that states ` +
+        `libc ${selector.libc} could never match a host. Remove libc.`,
+    });
+  }
+  return out;
+}

package/src/builtins.ts

@@ -1,3 +1,4 @@
+import { PLATFORM_AXES } from "./artifact-axes.js";
 import { manifestFragment, manifestFragmentRef, withSchemaFragments } from "./manifest-schemas.js";
 
 /** A slot holding author-written JSON Schema. Localized and hoisted by
@@ -157,9 +158,70 @@ const LIBRARY_CANDIDATES_SCHEMA = {
       format: { type: "string" },
       path: { type: "string" },
       source: { type: "string" },
-      os: { type: "string" },
-      arch: { type: "string" },
-      libc: { type: "string" },
+      ...Object.fromEntries(PLATFORM_AXES.map((axis) => [axis, { type: "string" }])),
+    },
+    additionalProperties: false,
+  },
+};
+
+/** `native:` — the module's platform-specific files, one entry per logical name
+ *  per platform tuple. Closed, so a mistyped axis is a schema violation rather
+ *  than a platform-neutral entry. Grammar and rules live in
+ *  `analyzer/nodejs/src/native-entries.ts` and `validate-native-entries.ts`. */
+const NATIVE_ENTRIES_SCHEMA = {
+  type: "array",
+  items: {
+    type: "object",
+    required: ["name", "format", "os", "arch", "path"],
+    properties: {
+      name: { type: "string" },
+      format: { type: "string" },
+      path: { type: "string" },
+      ...Object.fromEntries(PLATFORM_AXES.map((axis) => [axis, { type: "string" }])),
+    },
+    additionalProperties: false,
+  },
+};
+
+/** `sources:` — where every staged file comes from, keyed by source name, each
+ *  entry keyed by the module-relative path it produces. Closed at every level.
+ *  An entry is a file (`upstream` + `member`, pinned with `sha256` +
+ *  `executable`) or a link (`target`); a mix of the two, and every other rule,
+ *  is reported by `analyzer/nodejs/src/validate-source-entries.ts`. `archive`
+ *  names the upstream's format. A source built in the repo names its build under
+ *  `build`, keyed by build system (`cargo: <crate dir>`), with the digest of its
+ *  build inputs (`inputs`). */
+const SOURCES_SCHEMA = {
+  type: "object",
+  additionalProperties: {
+    type: "object",
+    required: ["version", "url", "archive", "notices", "entries"],
+    properties: {
+      version: { type: "string" },
+      url: { type: "string" },
+      archive: { enum: ["tar.gz"] },
+      notices: { type: "array", minItems: 1, items: { type: "string" } },
+      build: {
+        type: "object",
+        required: ["cargo"],
+        properties: { cargo: { type: "string" }, inputs: { type: "string" } },
+        additionalProperties: false,
+      },
+      entries: {
+        type: "object",
+        additionalProperties: {
+          type: "object",
+          anyOf: [{ required: ["upstream", "member"] }, { required: ["target"] }],
+          properties: {
+            upstream: { type: "string" },
+            member: { type: "string" },
+            sha256: { type: "string" },
+            executable: { type: "boolean" },
+            target: { type: "string" },
+          },
+          additionalProperties: false,
+        },
+      },
     },
     additionalProperties: false,
   },
@@ -169,25 +231,18 @@ const LIBRARY_CANDIDATES_SCHEMA = {
  *  One entry per layer except the manifest layer, which cannot list its own hash
  *  inside itself and is pinned by the importer's `#sha256-...` instead. Shape and
  *  matching rules are normative in kernel/specs/module-artifact.md; the parser
- *  that enforces them is `artifact-layer-index.ts`. */
+ *  that enforces them is `artifact-layer-index.ts`. `role` stays open and
+ *  `selector` unconstrained: an entry for a newer runtime is skipped, not
+ *  rejected, and its selector is not examined (spec §3.1). A known role's
+ *  selector is validated by the parser, which `telo check` runs. */
 const LAYER_INDEX_SCHEMA = {
   type: "array",
   items: {
     type: "object",
     required: ["role", "blob", "integrity"],
     properties: {
-      role: { type: "string", enum: ["controller", "library", "assets", "common"] },
-      selector: {
-        type: "object",
-        required: ["format"],
-        properties: {
-          format: { type: "string" },
-          os: { type: "string" },
-          arch: { type: "string" },
-          libc: { type: "string" },
-        },
-        additionalProperties: false,
-      },
+      role: { type: "string", minLength: 1 },
+      selector: {},
       blob: { type: "string", pattern: "^sha256:[0-9a-f]{64}$" },
       integrity: { type: "string", pattern: "^sha256-[A-Za-z0-9_-]{43}$" },
     },
@@ -751,6 +806,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           items: { type: "string" },
         },
         assets: ASSETS_FILES_SCHEMA,
+        native: NATIVE_ENTRIES_SCHEMA,
+        sources: SOURCES_SCHEMA,
         layers: LAYER_INDEX_SCHEMA,
         filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // Inline imports — name-keyed map sugar for separate `Telo.Import`
@@ -924,6 +981,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           items: { type: "string" },
         },
         assets: ASSETS_FILES_SCHEMA,
+        native: NATIVE_ENTRIES_SCHEMA,
+        sources: SOURCES_SCHEMA,
         layers: LAYER_INDEX_SCHEMA,
         filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // Inline imports — same name-keyed map sugar as Telo.Application; the

package/src/call-graph.ts

@@ -53,6 +53,7 @@ import {
   possibleUses,
   readRefSlot,
   transfersControl,
+  type RefSlot,
   type RefUse,
   type RefUseCases,
 } from "./ref-slot.js";
@@ -399,6 +400,35 @@ function resolveUseAtSite(
   return { use: possibleUses(slot), unresolved: entry.useCases, unresolvedReason };
 }
 
+/**
+ * A slot's use at one concrete site of one resource, for a consumer that walks
+ * the kind's schema itself rather than reading the graph's edges.
+ *
+ * The same rule the graph applies to a resource-level edge — the same enclosing
+ * object, the same schema default — so a consumer and an edge cannot disagree
+ * about which case of a case map holds. `concretePath` is the site
+ * (`routes[0].handler`); `fieldPath` is the declaration it resolved from
+ * (`routes[].handler`), which is what the schema default is read against.
+ */
+export function resolveSlotUseAt(
+  slot: RefSlot,
+  resource: unknown,
+  rootSchema: Record<string, any> | undefined,
+  concretePath: string,
+  fieldPath: string,
+): Pick<CallGraphEdge, "use" | "unresolved" | "unresolvedReason"> {
+  const entry: RefFieldEntry = {
+    refs: slot.kinds,
+    uses: slot.uses,
+    isArray: false,
+    ...(slot.useCases ? { useCases: slot.useCases } : {}),
+  };
+  const schemaDefault = rootSchema
+    ? schemaDefaultOf(enclosingSchemaOf(rootSchema, fieldPath))
+    : NO_DEFAULT;
+  return resolveUseAtSite(entry, resource, concretePath, schemaDefault);
+}
+
 /** A resolved plain reference value (`{kind, name}`, optionally `alias`) — the
  *  shape `resolveRefSentinels` leaves at a ref site. NOT a step: a bare boot
  *  target written `!ref X` must not mint a step node. */

package/src/catch-scope.ts

@@ -86,7 +86,7 @@ export function buildEnclosers(
     const definition = definitionOf(manifest);
     if (!definition?.schema) continue;
     forEachDrivenSlot(definition.schema, manifest, (driven) => {
-      if (driven.kind !== "ref" || !driven.slot.throwsThrough) return;
+      if (driven.kind !== "ref" || !driven.slots.some(({ slot }) => slot.throwsThrough)) return;
       const target = resolveRefManifest(driven.data, ctx, moduleOf(manifest));
       if (!target || target === manifest) return;
       const list = enclosers.get(target);

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

@@ -441,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,
@@ -470,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