@telorun/analyzer 0.69.0 → 0.71.0

package/src/definition-registry.ts

@@ -2,6 +2,7 @@ import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import { KERNEL_BUILTINS } from "./builtins.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import {
   buildFieldMapAtPath,
   buildReferenceFieldMap,
@@ -372,9 +373,7 @@ export class DefinitionRegistry {
     // (e.g. `Ai.AgentStream` in a library that imports `Ai`), which the root/global
     // resolver doesn't know — using the global scope here left the base field map
     // unresolved, so Phase-5 injection saw no ref fields and skipped injection.
-    const ownModule = (resource.metadata as { module?: string } | undefined)?.module;
-    const moduleScope =
-      (ownModule ? aliasesByModule.get(ownModule) : undefined) ?? aliases;
+    const moduleScope = moduleAliasScope(resource.metadata, aliases, aliasesByModule);
 
     const baseMap = this.getFieldMapForKind(resource.kind, moduleScope);
     if (!baseMap) return undefined;
@@ -383,9 +382,7 @@ export class DefinitionRegistry {
     const def = this.resolve(resource.kind) ?? this.resolve(resolvedKind);
     // schema-from anchors resolve in the DEFINITION's module scope (where the anchor
     // kind is declared), which may differ from the resource's own module.
-    const ownerModule = (def?.metadata as { module?: string } | undefined)?.module;
-    const ownerScope =
-      (ownerModule ? aliasesByModule.get(ownerModule) : undefined) ?? aliases;
+    const ownerScope = moduleAliasScope(def?.metadata, aliases, aliasesByModule);
 
     const expanded: ReferenceFieldMap = new Map();
     for (const [path, entry] of baseMap) {

package/src/flatten-for-analyzer.ts

@@ -8,7 +8,7 @@ import {
   readResourceInputs,
   type ResourceInput,
 } from "./resource-input.js";
-import type { ZoneModuleDocuments } from "./zone-module-documents.js";
+import type { ModuleDocuments } from "./module-documents.js";
 
 /** One parsed `exports.resources` / `exports.kinds` entry. `name` is the exported
  *  instance name or kind suffix (the part after the dot, or the whole entry); `alias`
@@ -557,8 +557,8 @@ function canonicalizeInputKind(
  *  projection needs the internal dispatch chain to derive an export's open
  *  requirements. Only libraries that actually export instances are included:
  *  a library exporting nothing has no export contract to derive. */
-export function collectZoneModuleDocuments(graph: LoadedGraph): ZoneModuleDocuments[] {
-  const out: ZoneModuleDocuments[] = [];
+export function collectModuleDocuments(graph: LoadedGraph): ModuleDocuments[] {
+  const out: ModuleDocuments[] = [];
   for (const [source, mod] of graph.modules) {
     if (source === graph.rootSource) continue;
     const libDoc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind)) as

package/src/index.ts

@@ -11,7 +11,7 @@ export type {
     ParseError,
 } from "./loaded-types.js";
 export {
-    collectZoneModuleDocuments,
+    collectModuleDocuments,
     flattenForAnalyzer,
     flattenLoadedModule,
     forwardReExportManifests,
@@ -127,6 +127,14 @@ export type {
   ResourceGraphNode,
   StepGraphNode,
 } from "./call-graph.js";
+export { celResourceReads } from "./cel-access-chains.js";
+export { declarationSignature, diffManifests } from "./manifest-diff.js";
+export type {
+  DiffEntry,
+  ManifestDiff,
+  ManifestDiffOptions,
+  ResourceChangeKind,
+} from "./manifest-diff.js";
 export {
   AMBIENT_CAPABILITIES,
   buildModuleGraph,
@@ -238,7 +246,7 @@ export type {
   ZoneExportRequirements,
   ZoneRequirementSpec,
 } from "./resolve-zone-requirements.js";
-export type { ZoneModuleDocuments } from "./zone-module-documents.js";
+export type { ModuleDocuments } from "./module-documents.js";
 export { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
 export {
   RESOURCE_RULES_ANNOTATION,

package/src/manifest-diff.ts

@@ -0,0 +1,219 @@
+/**
+ * What changed between two loads of one manifest set.
+ *
+ * The question a reconciling host asks before it touches anything: which
+ * resources survive an edit untouched, which have to be rebuilt, which are new,
+ * and which are gone. It is here rather than in the kernel because it is pure
+ * data in and data out and the editor wants the same answer — to show which
+ * resources a save would restart, in a browser, where no kernel runs.
+ *
+ * **This is the DECLARATION half of the question and only that half.** A field
+ * written `!cel "variables.port"` has the same declaration whatever the
+ * environment says, so a host that resolves configuration outside the manifest
+ * has to supply what moved there (`modulesWithChangedConfig`). Keeping the two
+ * apart is what lets this run in a browser at all.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+import { isCompiledValue } from "@telorun/sdk";
+import { nodeIdFor } from "./call-graph.js";
+import { canonicalJson } from "./canonical-json.js";
+import { DERIVED_METADATA_FIELDS } from "./module-metadata-scope.js";
+
+/** How one resource differs between the two sets. `unchanged` is reported as a
+ *  bare id rather than an entry, since there is nothing to say about it. */
+export type ResourceChangeKind = "added" | "removed" | "changed";
+
+export interface DiffEntry {
+  /** {@link nodeIdFor} — module-scoped, so two libraries each declaring a
+   *  resource named `store` are two entries rather than one. */
+  readonly id: string;
+  readonly change: ResourceChangeKind;
+  /** The declaration as it stood. Absent for an addition. */
+  readonly previous?: ResourceManifest;
+  /** The declaration as it now stands. Absent for a removal. */
+  readonly next?: ResourceManifest;
+}
+
+export interface ManifestDiff {
+  /** Additions, removals and changes. Order follows the next set, then the
+   *  previous set for removals, so a caller rendering this reads it in
+   *  declaration order rather than in hash order. */
+  readonly entries: readonly DiffEntry[];
+  /** Ids present in both sets with an identical declaration. */
+  readonly unchanged: readonly string[];
+  /** Ids whose current instance is no longer valid: every removal and every
+   *  change. What a reconciling host unwinds, once it has closed this set under
+   *  the resources that HOLD them — which is the call graph's answer, not this
+   *  one's. */
+  readonly stale: readonly string[];
+  /** Declarations that have to be created: every addition and every change.
+   *  Named for the kernel's own `pendingResources`, which is where they go. */
+  readonly pending: readonly ResourceManifest[];
+}
+
+export interface ManifestDiffOptions {
+  /**
+   * Modules whose resolved configuration moved between the two loads, by
+   * `metadata.module`.
+   *
+   * Every resource of such a module is reported `changed` even where its
+   * declaration is identical, because a declaration is not the whole of what a
+   * resource is built from: `!cel "variables.port"` reads the same and means
+   * something else once the environment behind it moves. Only the host that
+   * resolved that environment can know, so it is an input rather than something
+   * derived here.
+   */
+  readonly modulesWithChangedConfig?: ReadonlySet<string>;
+
+  /**
+   * Signatures of the previous set, by node id, taken while those manifests
+   * were still declarations.
+   *
+   * A host that INSTALLS manifests does not keep declarations: the kernel
+   * registers the very objects it loaded, and resolving references writes live
+   * instances into them — a boot target's `!ref`, or a slot nested past the
+   * create-time shallow copy. Signing such an object afterwards renders those
+   * slots opaque and reports a change that never happened, which on a module
+   * document means escalating every reconciliation there is.
+   *
+   * An id absent from the map is signed from its manifest, so a caller that
+   * really is holding declarations passes nothing.
+   */
+  readonly previousSignatures?: ReadonlyMap<string, string>;
+}
+
+/** A value that is not part of the declaration and must not be walked into:
+ *  a live instance a host injected over a reference slot, a function, a class
+ *  instance of any kind. Rendering one as a constant keeps the walk finite and
+ *  acyclic; comparing two sets across the injection boundary is not supported
+ *  and is what {@link declarationSignature} documents against. */
+const OPAQUE = '"\\u0000opaque"';
+
+const isPlainObject = (value: object): boolean => {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+/**
+ * A resource's declaration, rendered so that two equal declarations render
+ * identically.
+ *
+ * Three things are normalized away, and each would otherwise report a change
+ * that is not one:
+ *
+ *  - **Loader stamps** (`DERIVED_METADATA_FIELDS`). `metadata.sourceLine` is the
+ *    load-bearing one: inserting a line anywhere in a file shifts it for every
+ *    resource below, so leaving it in would mark a whole file changed on any
+ *    edit and defeat the mechanism entirely.
+ *  - **A compiled expression** renders as its source text. What the author wrote
+ *    is the declaration; what it evaluates to depends on configuration, which
+ *    `modulesWithChangedConfig` carries instead.
+ *  - **Anything that is not plain data** renders as a constant. A host that has
+ *    injected live instances over its reference slots has manifests that are no
+ *    longer declarations, and walking one reaches a controller's object graph,
+ *    which is cyclic. Both sides must be declarations as loaded.
+ *
+ * The result is compared as a string rather than hashed: there is no collision
+ * to reason about, and a missed change here is a resource that silently keeps
+ * running against a declaration it no longer matches.
+ */
+export function declarationSignature(manifest: ResourceManifest): string {
+  const seen = new WeakSet<object>();
+
+  const render = (value: unknown): unknown => {
+    if (isCompiledValue(value)) {
+      const source = (value as { source?: unknown }).source;
+      return { "\u0000cel": typeof source === "string" ? source : null };
+    }
+    if (!value || typeof value !== "object") return value;
+    if (seen.has(value)) return "\u0000cycle";
+    if (Array.isArray(value)) {
+      seen.add(value);
+      return value.map(render);
+    }
+    if (!isPlainObject(value)) return OPAQUE;
+    seen.add(value);
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = render(entry);
+    }
+    return out;
+  };
+
+  const authoredMetadata: Record<string, unknown> = {};
+  const metadata = manifest.metadata as Record<string, unknown> | undefined;
+  for (const [key, value] of Object.entries(metadata ?? {})) {
+    if (DERIVED_METADATA_FIELDS.has(key)) continue;
+    authoredMetadata[key] = render(value);
+  }
+
+  const body: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(manifest as Record<string, unknown>)) {
+    if (key === "metadata") continue;
+    body[key] = render(value);
+  }
+
+  return canonicalJson({ ...body, metadata: authoredMetadata });
+}
+
+/**
+ * Classify every resource of two loads against each other.
+ *
+ * **Identity is `nodeIdFor`**, which is module-scoped, so a name is compared
+ * only against the same name in the same module. One consequence is worth
+ * stating because it is visible: an INLINE resource's name is synthesized from
+ * its position (`api_routes_0_handler`), so inserting a route above one renames
+ * every inline below it and this reports those as a removal plus an addition.
+ * That costs a restart it did not have to cost; it never misses a change, which
+ * is the direction that matters.
+ */
+export function diffManifests(
+  previous: readonly ResourceManifest[],
+  next: readonly ResourceManifest[],
+  options: ManifestDiffOptions = {},
+): ManifestDiff {
+  const before = new Map<string, ResourceManifest>();
+  for (const manifest of previous) before.set(nodeIdFor(manifest), manifest);
+
+  const changedConfig = options.modulesWithChangedConfig;
+  const configMoved = (manifest: ResourceManifest): boolean => {
+    if (!changedConfig || changedConfig.size === 0) return false;
+    const module = (manifest.metadata as { module?: string } | undefined)?.module;
+    return module !== undefined && changedConfig.has(module);
+  };
+
+  const entries: DiffEntry[] = [];
+  const unchanged: string[] = [];
+  const stale: string[] = [];
+  const pending: ResourceManifest[] = [];
+  const survived = new Set<string>();
+
+  for (const manifest of next) {
+    const id = nodeIdFor(manifest);
+    const prior = before.get(id);
+    if (!prior) {
+      entries.push({ id, change: "added", next: manifest });
+      pending.push(manifest);
+      continue;
+    }
+    survived.add(id);
+    const priorSignature =
+      options.previousSignatures?.get(id) ?? declarationSignature(prior);
+    const same = !configMoved(manifest) && priorSignature === declarationSignature(manifest);
+    if (same) {
+      unchanged.push(id);
+      continue;
+    }
+    entries.push({ id, change: "changed", previous: prior, next: manifest });
+    stale.push(id);
+    pending.push(manifest);
+  }
+
+  for (const [id, manifest] of before) {
+    if (survived.has(id)) continue;
+    entries.push({ id, change: "removed", previous: manifest });
+    stale.push(id);
+  }
+
+  return { entries, unchanged, stale, pending };
+}

package/src/manifest-visitor.ts

@@ -17,6 +17,7 @@ import {
   type SchemaFromFieldEntry,
 } from "./reference-field-map.js";
 import type { ModuleScopes } from "./alias-resolver.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import { templateBodies, withTemplateSelf } from "./template-body.js";
 import { extractContextsFromSchema, pathMatchesScope } from "./validate-cel-context.js";
 
@@ -237,7 +238,14 @@ export function visitManifest(
     if (!r.metadata?.name || !r.kind) continue;
     if (skipKinds?.has(r.kind)) continue;
 
-    const resolvedKind = aliases?.resolveKind(r.kind);
+    // A resource's own kind is written in the alias scope of the module that
+    // DECLARED it — see `moduleAliasScope`, which is the one place that rule
+    // lives. Resolving it through the entry's aliases alone left `definition`
+    // undefined for every forwarded resource, so its `x-telo-context` regions
+    // contributed nothing and `request` / `result` read as unknown identifiers
+    // inside the library's own routes, on a file the consumer cannot fix.
+    const moduleScope = moduleAliasScope(r.metadata, aliases, aliasesByModule);
+    const resolvedKind = moduleScope?.resolveKind(r.kind);
     const definition =
       registry.resolve(r.kind) ??
       (resolvedKind ? registry.resolve(resolvedKind) : undefined);
@@ -249,8 +257,8 @@ export function visitManifest(
     const emittedRefPaths = wantsNested ? new Set<string>() : null;
 
     if (wantsRefs || wantsScope || wantsSchemaFrom) {
-      const baseMap = aliases
-        ? registry.getFieldMapForKind(r.kind, aliases)
+      const baseMap = moduleScope
+        ? registry.getFieldMapForKind(r.kind, moduleScope)
         : registry.getFieldMap(r.kind);
 
       // Expanded map drives ref/scope sites when requested; schema-from sites

package/src/module-alias-scope.ts

@@ -0,0 +1,94 @@
+import { AliasResolver, scopeResolverForModule, type ModuleScopes } from "./alias-resolver.js";
+
+/**
+ * WHICH ALIAS TABLE A MANIFEST'S OWN NAMES ARE WRITTEN IN.
+ *
+ * An application analysis is flattened, so an imported library's definitions and
+ * exported instances are checked in the CONSUMER's pass. But every alias-qualified
+ * name on such a manifest — its `kind:`, its `extends:`, an `x-telo-schema-from`
+ * anchor — was written against the alias map of the module that DECLARED it. A
+ * library writes `kind: Http.Api` through an import the consumer has no reason to
+ * have, so resolving it through the entry's table finds nothing, and everything
+ * derived from the definition silently goes missing: the field map (Phase-5
+ * injection blind to a forwarded resource's ref slots) and the `x-telo-context`
+ * regions (`request` / `result` reported as unknown identifiers on a file the
+ * consumer cannot edit).
+ *
+ * **There are TWO fallbacks, not one, and this file is where they are told
+ * apart** — that is the whole reason they live together. They agree on every
+ * module that has a table, and differ on a non-root module that has none:
+ *
+ *  - {@link moduleAliasScope} falls back to the GLOBAL table. For a question
+ *    asked about an arbitrary manifest, where a missing entry means "this is the
+ *    entry's own", which is what the global table answers correctly.
+ *  - {@link declaringModuleScope} falls back to an EMPTY table for a non-root
+ *    module. For canonicalizing what a library DECLARED, where resolving its
+ *    `Http.Api` through the consumer's imports would silently bind a library's
+ *    kind to whatever the app happens to import under that alias — a wrong
+ *    answer, which is worse than none.
+ *
+ * Both rest on one invariant neither states inline: **a root module is never a
+ * key in `aliasesByModule`** — a root's imports are registered into the global
+ * table instead (see the `rootModules` guards in `analyze()`) — so for a
+ * consumer-owned manifest the two rules coincide and neither fallback is a
+ * degradation.
+ *
+ * Every READ of the rule goes through one of these two. What legitimately does
+ * not, and why, so the next reader does not have to re-derive it: the three
+ * sites in `analyze()` that POPULATE `aliasesByModule` (a write, not a lookup),
+ * and `resolve-ref-sentinels`, whose module is known non-root by construction and
+ * whose fallback is the raw kind rather than another table — a different rule
+ * that happens to read the same map.
+ */
+export function moduleAliasScope<A extends KindResolver, M extends KindResolver>(
+  metadata: { module?: unknown } | undefined,
+  aliases: A,
+  aliasesByModule: ReadonlyMap<string, M> | undefined,
+): A | M;
+export function moduleAliasScope<A extends KindResolver, M extends KindResolver>(
+  metadata: { module?: unknown } | undefined,
+  aliases: A | undefined,
+  aliasesByModule: ReadonlyMap<string, M> | undefined,
+): A | M | undefined;
+export function moduleAliasScope<A extends KindResolver, M extends KindResolver>(
+  metadata: { module?: unknown } | undefined,
+  aliases: A | undefined,
+  aliasesByModule: ReadonlyMap<string, M> | undefined,
+): A | M | undefined {
+  const declaringModule = metadata?.module;
+  if (typeof declaringModule !== "string") return aliases;
+  return aliasesByModule?.get(declaringModule) ?? aliases;
+}
+
+/** 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
+ *  the one site that does (a template body) reach for a cast. */
+interface KindResolver {
+  resolveKind(kind: string): string | undefined;
+}
+
+/** An empty table, shared: a non-root module with no aliases of its own resolves
+ *  nothing rather than resolving through the consumer's. One instance because it
+ *  is immutable in use and allocating one per call put a resolver on a per-schema
+ *  loop. */
+const NO_ALIASES = new AliasResolver();
+
+/**
+ * The scope a DECLARING module's own alias-form names are canonicalized in — the
+ * root-aware half of the rule above, and the one that must never fall through to
+ * the consumer's table. See this file's header for why the two differ.
+ */
+export function declaringModuleScope(
+  ownModule: string | undefined,
+  aliases: AliasResolver,
+  scopes: { aliasesByModule: Map<string, AliasResolver>; rootModules: Set<string> },
+): AliasResolver {
+  const own = scopeResolverForModule(ownModule, scopes.rootModules, scopes.aliasesByModule);
+  if (own) return own;
+  // Root (or unknown-and-therefore-treated-as-root): the global table IS its
+  // import map. A non-root module with no table of its own resolves nothing.
+  return ownModule && !scopes.rootModules.has(ownModule) ? NO_ALIASES : aliases;
+}
+
+export type { ModuleScopes };

package/src/{zone-module-documents.ts → module-documents.ts}

@@ -1,19 +1,23 @@
 import type { ResourceManifest } from "@telorun/sdk";
 
 /**
- * One imported library's FULL document set, for the zone stage's per-library
- * export derivation — what the flattened analysis view no longer holds, since
- * it forwards only each library's export surface and never its internal
- * dispatch chain.
+ * One imported library's FULL document set — what the flattened analysis view
+ * no longer holds, since it forwards only each library's export surface and
+ * never its internal dispatch chain.
+ *
+ * Named for what it CARRIES rather than for who asked first: the zone stage's
+ * per-library export derivation was the original consumer, and the throws walk
+ * is the second — a third should not have to import "zone" to ask about
+ * something else again.
  *
  * Plain data in a module of its own, deliberately. It is produced by the
- * loading side (`collectZoneModuleDocuments`), named in `AnalysisOptions`, and
+ * loading side (`collectModuleDocuments`), named in `AnalysisOptions`, and
  * consumed by the projection; putting it in any of the three would make the
  * other two import that one, and `types.ts` ↔ the projection is a genuine
  * cycle. A leaf module with no imports of its own breaks it without an inline
  * `import(...)` type expression standing in for the dependency nobody wanted.
  */
-export interface ZoneModuleDocuments {
+export interface ModuleDocuments {
   /** The library's module name (its `Telo.Library` doc's `metadata.name`). */
   module: string;
   /** Stable source identity of the library's owner file — the cache key. */

package/src/module-graph.ts

@@ -65,6 +65,8 @@ import { isStepSlot } from "./step-slot.js";
 import { isInlineResource, resolveFieldEntries } from "./reference-field-map.js";
 import { findZoneProviders } from "./resolve-zone-containment.js";
 import { possibleUses, readRefSlot, type RefUse } from "./ref-slot.js";
+import { canonicalJson } from "./canonical-json.js";
+import { accessChains } from "./cel-access-chains.js";
 
 /** How a node's declaration reached the module, which is what decides where a
  *  view may draw it — an inline child exists nowhere but its parent's YAML, so
@@ -591,15 +593,6 @@ export function contentKey(value: unknown): string {
   return hash.toString(36);
 }
 
-function canonicalJson(value: unknown): string {
-  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  const entries = Object.entries(value as Record<string, unknown>)
-    .filter(([, v]) => v !== undefined)
-    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
-}
-
 /** Mints ids that are unique without being positional: the name where one
  *  exists, a content key where none does, and a `~n` suffix only when two
  *  siblings are genuinely indistinguishable. */
@@ -1940,21 +1933,6 @@ function buildKindPlane(
   return out;
 }
 
-/** The CEL environment used to PARSE a chain out of an expression. One per
- *  process: building it is the expensive half, and nothing here evaluates. */
-let parseEnv: ReturnType<typeof buildCelEnvironment> | undefined;
-
-/** Access chains an expression reads, or none when it does not parse — a syntax
- *  error is the engine pass's to report, not this one's. */
-function accessChains(source: string): string[][] {
-  try {
-    parseEnv ??= buildCelEnvironment();
-    return extractAccessChains(parseEnv.parse(source).ast);
-  } catch {
-    return [];
-  }
-}
-
 /**
  * Every `resources.<name>…` read in one resource's CEL, as an edge.
  *

package/src/ref-sentinel-target.ts

@@ -0,0 +1,46 @@
+import { isRefSentinel } from "@telorun/templating";
+
+/**
+ * What a `!ref` names, parsed once.
+ *
+ * THE single reader of the tag's grammar, on the `ref-slot.ts` / `zone-slot.ts`
+ * precedent. Three passes had grown their own parse of the same scalar and they
+ * disagreed: one took the source verbatim, one split on the first dot and
+ * dropped every alias but `Self`, one split on the LAST dot and dropped the
+ * alias entirely — so the same `!ref Alias.name` named three different things
+ * depending on which pass was asking, and the loosest of the three resolved a
+ * bare name against whatever manifest happened to share it.
+ *
+ * The grammar itself is one line and is not in dispute: `!ref <name>` or
+ * `!ref <Alias>.<name>`, split on the FIRST dot, because that is what
+ * `resolveRefSentinels` does and a name may not contain one
+ * (`INVALID_NAME` rejects it at every declaration site).
+ *
+ * What this deliberately does NOT do is decide what to look up. A reduction is
+ * the caller's, and the three genuinely differ: an edge in the call graph points
+ * at a cross-module target and tolerates not resolving it; a zone correlation
+ * refuses to bind anything it cannot resolve exactly; a throws walk resolves in
+ * the DECLARING library first. Each states its own, over one parse.
+ *
+ * Browser-safe.
+ */
+export interface RefSentinelTarget {
+  /** The scalar as written, for a caller that wants the author's spelling. */
+  source: string;
+  /** The prefix before the first dot, `Self` included and not normalized away —
+   *  a caller that treats `Self` as "no alias" says so itself. */
+  alias?: string;
+  /** The segment after the first dot, or the whole scalar when there is none. */
+  name: string;
+}
+
+/** Parse a `!ref` sentinel. Returns `undefined` for anything that is not one —
+ *  including the `{kind, name}` object `resolveRefSentinels` rewrites it into,
+ *  which is a different shape with a different reader. */
+export function refSentinelTarget(value: unknown): RefSentinelTarget | undefined {
+  if (!isRefSentinel(value)) return undefined;
+  const source = value.source;
+  const dot = source.indexOf(".");
+  if (dot <= 0) return { source, name: source };
+  return { source, alias: source.slice(0, dot), name: source.slice(dot + 1) };
+}

package/src/resolve-schema-type-refs.ts

@@ -1,6 +1,7 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId, parseTeloTypeRef } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 
 /** Schema-bearing fields on a Telo.Definition / Telo.Type resource. */
 const SCHEMA_FIELDS = ["schema", "inputType", "outputType"];
@@ -96,7 +97,7 @@ export function resolveSchemaTypeRefs(
 
   for (const r of resources) {
     const ownModule = (r.metadata as { module?: string } | undefined)?.module;
-    const resolver = (ownModule ? aliasesByModule?.get(ownModule) : undefined) ?? aliases;
+    const resolver = moduleAliasScope(r.metadata, aliases, aliasesByModule);
     const resolveAuthority = (authority: string): string | undefined =>
       authority === "Self" ? ownModule : resolver?.moduleForAlias(authority);
     for (const field of SCHEMA_FIELDS) {