@telorun/analyzer 0.72.0 → 0.74.0

package/dist/validate-observed-state.js

@@ -1,5 +1,6 @@
 import { OBSERVED_STATE_KEY } from "@telorun/sdk";
 import { effectiveStatusSchema } from "./extends-resolution.js";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
 import { parseExportEntry } from "./flatten-for-analyzer.js";
 import { moduleScopedDefResolver, } from "./alias-resolver.js";
 import { buildReferenceFieldMap, isScopeEntry, resolveFieldValues, } from "./reference-field-map.js";
@@ -100,6 +101,10 @@ export function collectRunReachableNames(graph) {
         names.add(edge.toName);
     return names;
 }
+/** The index key of a name a dependency declares, as read from inside it. */
+export function forwardedResourceKey(module, name) {
+    return `${module}\0${name}`;
+}
 /**
  * Index every resource a CEL `resources.…` read can name: the module's own
  * top-level resources, the ones declared inside `x-telo-scope` slots (a
@@ -115,17 +120,30 @@ export function buildObservedStateIndex(manifests, defs, aliases, scopes) {
     /** `module` is the resource's DECLARING module: an exported instance is
      *  written with that library's aliases (`kind: Self.Listener`), which the
      *  consumer's table cannot resolve. */
-    const record = (kind, key, scoped, module) => {
+    const record = (kind, key, scoped, module, forwardedFrom) => {
         const status = effectiveStatusSchema(resolve.in(kind, module), resolve);
-        out.set(key, { kind, ...(status ? { status } : {}), ...(scoped ? { scoped } : {}) });
+        out.set(key, {
+            kind,
+            ...(status ? { status } : {}),
+            ...(scoped ? { scoped } : {}),
+            ...(forwardedFrom !== undefined ? { forwardedFrom } : {}),
+        });
     };
     for (const manifest of manifests) {
         const kind = manifest.kind;
         const name = manifest.metadata?.name;
         if (!kind || SYSTEM_KINDS.has(kind))
             continue;
+        const module = manifest.metadata?.module;
+        // A dependency's declarations publish into ITS module's `resources`, not this
+        // one's: they are keyed by that module, and an export is also indexed under
+        // `<Alias>.<name>` below.
+        const forwardedFrom = isForwardedDeclaration(manifest) ? module : undefined;
+        if (forwardedFrom === undefined && isForwardedDeclaration(manifest))
+            continue;
+        const keyOf = (n) => forwardedFrom === undefined ? n : forwardedResourceKey(forwardedFrom, n);
         if (name)
-            record(kind, name, false, manifest.metadata?.module);
+            record(kind, keyOf(name), false, module, forwardedFrom);
         const schema = resolve(kind)?.schema;
         if (!schema)
             continue;
@@ -137,7 +155,7 @@ export function buildObservedStateIndex(manifests, defs, aliases, scopes) {
                     const scopedKind = scopedEntry?.kind;
                     const scopedName = scopedEntry?.metadata?.name;
                     if (typeof scopedKind === "string" && typeof scopedName === "string") {
-                        record(scopedKind, scopedName, true);
+                        record(scopedKind, keyOf(scopedName), true, forwardedFrom, forwardedFrom);
                     }
                 }
             }
@@ -207,8 +225,8 @@ function* importedExports(manifests, aliases) {
  *  flat field pass exactly as they do today. */
 export function buildObservedStateResourcesSchema(index, open) {
     const properties = {};
-    for (const [key, { status }] of index) {
-        if (!status)
+    for (const [key, { status, forwardedFrom }] of index) {
+        if (!status || forwardedFrom !== undefined)
             continue;
         applyObservedStateNode(properties, key, status);
     }

package/dist/validate-provider-coherence.d.ts

@@ -12,20 +12,16 @@ import { type AnalysisDiagnostic } from "./types.js";
  *    `capability` is not `Telo.Provider`.
  *  - PROVIDE_DISPATCHER_CONFLICT: `provide:` co-exists with `invoke:` or `run:`
  *    on the same definition.
- *  - PROVIDE_TARGET_UNKNOWN: `provide.name` does not resolve to an entry in
- *    `resources:`.
- *  - PROVIDE_TARGET_NOT_INVOCABLE: `provide.name` resolves to a resource whose
- *    kind is registered but not a `Telo.Invocable`.
  *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
  *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
  *  - MOUNT_ON_NON_MOUNT: `mount:` declared on a definition whose `capability` is
  *    not `Telo.Mount`.
  *  - MOUNT_DISPATCHER_CONFLICT: `mount:` co-exists with another dispatch
  *    entry-point (`invoke:` / `run:` / `provide:`).
- *  - MOUNT_TARGET_UNKNOWN: `mount.name` does not resolve to an entry in
- *    `resources:`.
- *  - MOUNT_TARGET_NOT_MOUNTABLE: `mount.name` resolves to a resource whose kind
- *    is registered but not a `Telo.Mount`.
+ *
+ * What a dispatch slot NAMES — that it is a `!ref`, that the entry exists, that
+ * its capability carries the method — is `validate-template-body`'s, for every
+ * slot alike.
  */
 export declare function validateProviderCoherence(manifests: ResourceManifest[], registry: DefinitionRegistry, aliases: AliasResolver): AnalysisDiagnostic[];
 //# sourceMappingURL=validate-provider-coherence.d.ts.map

package/dist/validate-provider-coherence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-provider-coherence.d.ts","sourceRoot":"","sources":["../src/validate-provider-coherence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CA+NtB"}
+{"version":3,"file":"validate-provider-coherence.d.ts","sourceRoot":"","sources":["../src/validate-provider-coherence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAMnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CAiHtB"}

package/dist/validate-provider-coherence.js

@@ -1,4 +1,4 @@
-import { controllerBearingAncestor } from "./extends-resolution.js";
+import { controllerBearingAncestor, inheritedCapability, } from "./extends-resolution.js";
 import { DiagnosticSeverity } from "./types.js";
 const SOURCE = "telo-analyzer";
 /**
@@ -11,20 +11,16 @@ const SOURCE = "telo-analyzer";
  *    `capability` is not `Telo.Provider`.
  *  - PROVIDE_DISPATCHER_CONFLICT: `provide:` co-exists with `invoke:` or `run:`
  *    on the same definition.
- *  - PROVIDE_TARGET_UNKNOWN: `provide.name` does not resolve to an entry in
- *    `resources:`.
- *  - PROVIDE_TARGET_NOT_INVOCABLE: `provide.name` resolves to a resource whose
- *    kind is registered but not a `Telo.Invocable`.
  *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
  *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
  *  - MOUNT_ON_NON_MOUNT: `mount:` declared on a definition whose `capability` is
  *    not `Telo.Mount`.
  *  - MOUNT_DISPATCHER_CONFLICT: `mount:` co-exists with another dispatch
  *    entry-point (`invoke:` / `run:` / `provide:`).
- *  - MOUNT_TARGET_UNKNOWN: `mount.name` does not resolve to an entry in
- *    `resources:`.
- *  - MOUNT_TARGET_NOT_MOUNTABLE: `mount.name` resolves to a resource whose kind
- *    is registered but not a `Telo.Mount`.
+ *
+ * What a dispatch slot NAMES — that it is a `!ref`, that the entry exists, that
+ * its capability carries the method — is `validate-template-body`'s, for every
+ * slot alike.
  */
 export function validateProviderCoherence(manifests, registry, aliases) {
     const diagnostics = [];
@@ -50,13 +46,18 @@ export function validateProviderCoherence(manifests, registry, aliases) {
         const resource = { kind: m.kind, name };
         const label = `${m.kind}/${name}`;
         const md = m;
-        const capability = typeof md.capability === "string" ? md.capability : undefined;
+        const resolveDef = (k) => registry.resolve(aliases.resolveKind(k) ?? k) ?? registry.resolve(k);
+        // The INHERITED capability, not the declared one: an `extends` child writes
+        // none of its own, so reading `md.capability` reported a child that inherits
+        // `Telo.Provider` and declares `provide:` as PROVIDE_ON_NON_PROVIDER
+        // "(found '<unset>')" — the same defect `celRuleApplies` and
+        // `validate-template-body` were fixed for, in the file next door.
+        const capability = inheritedCapability(m, resolveDef);
         const provide = md.provide;
         const invoke = md.invoke;
         const run = md.run;
         const mount = md.mount;
         const controllers = md.controllers;
-        const resources = md.resources;
         const hasProvide = provide !== undefined && provide !== null;
         const hasInvoke = invoke !== undefined && invoke !== null;
         const hasRun = run !== undefined && run !== null;
@@ -83,67 +84,6 @@ export function validateProviderCoherence(manifests, registry, aliases) {
                 data: { resource, filePath, path: "provide" },
             });
         }
-        if (hasProvide && typeof provide === "object" && !Array.isArray(provide)) {
-            const provideObj = provide;
-            const providedName = typeof provideObj.name === "string" ? provideObj.name : undefined;
-            const providedKind = typeof provideObj.kind === "string" ? provideObj.kind : undefined;
-            if (providedName && Array.isArray(resources)) {
-                const match = resources.find((r) => {
-                    const meta = r?.metadata;
-                    return typeof meta?.name === "string" && meta.name === providedName;
-                });
-                if (!match) {
-                    diagnostics.push({
-                        severity: DiagnosticSeverity.Error,
-                        code: "PROVIDE_TARGET_UNKNOWN",
-                        source: SOURCE,
-                        message: `${label}: 'provide.name: ${providedName}' does not match any entry's ` +
-                            `metadata.name in 'resources:'.`,
-                        data: { resource, filePath, path: "provide.name" },
-                    });
-                }
-                else if (typeof match.kind === "string") {
-                    // `provide.kind` is the type contract the analyzer uses to type
-                    // `result` CEL against the target's `outputType`. The runtime
-                    // dispatches on `provide.name` and ignores `provide.kind`, so a
-                    // mismatch silently degrades `result` typing to an open schema
-                    // (and at runtime quietly invokes the actually-matched resource).
-                    // Flag the divergence so result-typing never lies.
-                    if (providedKind) {
-                        const providedCanonical = aliases.resolveKind(providedKind) ?? providedKind;
-                        const matchCanonical = aliases.resolveKind(match.kind) ?? match.kind;
-                        if (providedCanonical !== matchCanonical) {
-                            diagnostics.push({
-                                severity: DiagnosticSeverity.Error,
-                                code: "PROVIDE_KIND_MISMATCH",
-                                source: SOURCE,
-                                message: `${label}: 'provide.kind: ${providedKind}' disagrees with the matched ` +
-                                    `'resources:' entry's kind '${match.kind}' (matched by metadata.name ` +
-                                    `'${providedName}'). The runtime dispatches by name, so 'provide.kind' ` +
-                                    `is decorative — but the analyzer types 'result:' against it, and a ` +
-                                    `mismatch silently turns off that typing.`,
-                                data: { resource, filePath, path: "provide.kind" },
-                            });
-                        }
-                    }
-                    const resolvedKind = aliases.resolveKind(match.kind) ?? match.kind;
-                    const targetDef = registry.resolve(resolvedKind) ?? registry.resolve(match.kind);
-                    if (targetDef && targetDef.kind === "Telo.Definition") {
-                        const targetCap = targetDef.capability;
-                        if (typeof targetCap === "string" && targetCap !== "Telo.Invocable") {
-                            diagnostics.push({
-                                severity: DiagnosticSeverity.Error,
-                                code: "PROVIDE_TARGET_NOT_INVOCABLE",
-                                source: SOURCE,
-                                message: `${label}: 'provide.name: ${providedName}' resolves to a ${match.kind} ` +
-                                    `(capability '${targetCap}'); 'provide:' requires a Telo.Invocable target.`,
-                                data: { resource, filePath, path: "provide.name" },
-                            });
-                        }
-                    }
-                }
-            }
-        }
         if (hasMount && capability !== "Telo.Mount") {
             diagnostics.push({
                 severity: DiagnosticSeverity.Error,
@@ -165,60 +105,9 @@ export function validateProviderCoherence(manifests, registry, aliases) {
                 data: { resource, filePath, path: "mount" },
             });
         }
-        if (hasMount) {
-            // Resolve the target's name from either form: the bare string (the
-            // primary, documented form — `mount: api`) or the object's `name`. A CEL
-            // target (`${{ … }}`) can only be checked at runtime, so skip those.
-            let mountedName;
-            if (typeof mount === "string") {
-                if (!mount.includes("${{"))
-                    mountedName = mount;
-            }
-            else if (typeof mount === "object" && !Array.isArray(mount)) {
-                const mountObj = mount;
-                if (typeof mountObj.name === "string" && !mountObj.name.includes("${{")) {
-                    mountedName = mountObj.name;
-                }
-            }
-            const mountPath = typeof mount === "string" ? "mount" : "mount.name";
-            if (mountedName && Array.isArray(resources)) {
-                const match = resources.find((r) => {
-                    const meta = r?.metadata;
-                    return typeof meta?.name === "string" && meta.name === mountedName;
-                });
-                if (!match) {
-                    diagnostics.push({
-                        severity: DiagnosticSeverity.Error,
-                        code: "MOUNT_TARGET_UNKNOWN",
-                        source: SOURCE,
-                        message: `${label}: '${mountPath}: ${mountedName}' does not match any entry's ` +
-                            `metadata.name in 'resources:'.`,
-                        data: { resource, filePath, path: mountPath },
-                    });
-                }
-                else if (typeof match.kind === "string") {
-                    const resolvedKind = aliases.resolveKind(match.kind) ?? match.kind;
-                    const targetDef = registry.resolve(resolvedKind) ?? registry.resolve(match.kind);
-                    if (targetDef && targetDef.kind === "Telo.Definition") {
-                        const targetCap = targetDef.capability;
-                        if (typeof targetCap === "string" && targetCap !== "Telo.Mount") {
-                            diagnostics.push({
-                                severity: DiagnosticSeverity.Error,
-                                code: "MOUNT_TARGET_NOT_MOUNTABLE",
-                                source: SOURCE,
-                                message: `${label}: '${mountPath}: ${mountedName}' resolves to a ${match.kind} ` +
-                                    `(capability '${targetCap}'); 'mount:' requires a Telo.Mount target.`,
-                                data: { resource, filePath, path: mountPath },
-                            });
-                        }
-                    }
-                }
-            }
-        }
         // A definition that inherits a controller by delegation (concrete `extends`,
         // no own controller/template) satisfies the implementation requirement
         // through its parent — `base:` supplies the parent's config.
-        const resolveDef = (k) => registry.resolve(aliases.resolveKind(k) ?? k) ?? registry.resolve(k);
         const inheritsController = typeof md.extends === "string" &&
             controllerBearingAncestor(m, resolveDef) !== undefined;
         if (capability === "Telo.Provider" && !hasControllers && !hasProvide && !inheritsController) {

package/dist/validate-reference-forms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-reference-forms.d.ts","sourceRoot":"","sources":["../src/validate-reference-forms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,kBAAkB,EAAE,CA0EtB"}
+{"version":3,"file":"validate-reference-forms.d.ts","sourceRoot":"","sources":["../src/validate-reference-forms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAKnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,kBAAkB,EAAE,CAwEtB"}

package/dist/validate-reference-forms.js

@@ -1,4 +1,5 @@
 import { isTaggedSentinel } from "@telorun/templating";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
 import { visitManifest } from "./manifest-visitor.js";
 import { satisfiesValueBranch } from "./reference-field-map.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
@@ -40,8 +41,7 @@ export function validateReferenceForms(resources, registry, aliases, aliasesByMo
     if (!aliases)
         return [];
     const diagnostics = [];
-    const isForeign = (r) => r.metadata?.forwardedExport === true;
-    const localResources = resources.filter((r) => !isForeign(r));
+    const localResources = resources.filter((r) => !isForwardedDeclaration(r));
     visitManifest(localResources, registry, {
         onRef: (e) => {
             const value = e.value;

package/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAarD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAE/F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAMnE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,kBAAkB;AAC5B;8EAC8E;AAC9E,aAAa,UAAQ,GACpB,OAAO,CAwBT;AAgED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAwjBtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAarD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAE/F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AA2InE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,kBAAkB;AAC5B;8EAC8E;AAC9E,aAAa,UAAQ,GACpB,OAAO,CAwBT;AAgED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAwgBtB"}

package/dist/validate-references.js

@@ -6,8 +6,141 @@ import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
 import { DiagnosticSeverity } from "./types.js";
 import { moduleAliasScope } from "./module-alias-scope.js";
+import { isModuleKind } from "./module-kinds.js";
 import { isInjectedDeclaration } from "./resource-input.js";
+import { outsideScopesOf } from "./scope-declarations.js";
+import { isForwardedDeclaration, isForwardedExport } from "./forwarded-declaration.js";
 const SOURCE = "telo-analyzer";
+/** What a name IS on one side of a collision. The three shapes share the
+ *  kernel's one namespace but read as different things to an author — an alias
+ *  is not a resource, and a module's own name is not a declaration inside it —
+ *  so calling all three "resource name" describes two of them wrongly. */
+function describeNamed(m, name) {
+    if (m.kind === "Telo.Import")
+        return `import alias '${name}'`;
+    if (isModuleKind(m.kind))
+        return `this module's own name (${m.kind} '${name}')`;
+    return `resource ${m.kind}/${name}`;
+}
+/**
+ * WHAT SHARES A NAME AT THE KERNEL.
+ *
+ * `registerManifest` keys on `metadata.name` alone, per module context, for
+ * EVERY kind — so an import alias, a kind definition and an ordinary resource
+ * are one namespace. This check used to model a narrower one: `Telo.Import` was
+ * excluded outright, on the stated grounds that an alias "lives in a separate
+ * namespace from resources", and `Telo.Definition` / `Telo.Abstract` fell out
+ * through the ref-validation skip set, which answers a different question. All
+ * three passed `telo check` and then died at boot with `ERR_DUPLICATE_RESOURCE`
+ * — an application named after one of its own imports (`metadata.name: Schedule`
+ * beside `Schedule: oci://…/scheduler`) being the shape that reaches an author,
+ * since nothing about the two lines looks like one name written twice.
+ *
+ * Grouped per DECLARING MODULE, which is what makes including imports sound: a
+ * library's own `Telo.Import` / `Telo.Definition` docs are forwarded into a
+ * consumer's flat set, and two modules sharing an alias (`Console` in an app and
+ * again in a library it imports) is ordinary rather than a collision. A module
+ * doc carries no `metadata.module` and IS its own scope — that is what puts an
+ * application's own name in the same group as its imports.
+ *
+ * Kept apart from the resolution lookup it used to share a map with: that one
+ * must hold resolution targets alone, so the two disagree about membership by
+ * design and merging them re-keyed every bare-name reference.
+ */
+function duplicateNameDiagnostics(resources, isForeign, moduleOf) {
+    const diagnostics = [];
+    const moduleDocNames = new Set();
+    for (const r of resources) {
+        if (isModuleKind(r.kind) && typeof r.metadata?.name === "string") {
+            moduleDocNames.add(r.metadata.name);
+        }
+    }
+    // A module doc belongs in the scope its OWN resources are in. Flattened, they
+    // carry `metadata.module` equal to its name, so it scopes to itself — which is
+    // what puts an application's name beside its imports. Unflattened (a hand-built
+    // fixture, a single-file editor analysis) nothing is stamped, so its resources
+    // sit in the unnamed scope and the doc has to join them there or a collision
+    // with one of them splits across two groups and goes unreported.
+    const stampedModules = new Set();
+    for (const r of resources) {
+        const m = moduleOf(r);
+        if (m)
+            stampedModules.add(m);
+    }
+    // scope → name → declarations, so no separator has to be safe against a name.
+    const byScope = new Map();
+    const seen = new Set();
+    for (const r of resources) {
+        if (!r.metadata?.name || isForeign(r))
+            continue;
+        const name = r.metadata.name;
+        const scope = isModuleKind(r.kind)
+            ? (stampedModules.has(name) ? name : "")
+            : (moduleOf(r) ?? "");
+        // A scope with no module doc in this set is an imported library's, whose
+        // doc `selectModuleManifestsForAnalysis` drops — its internals are its own
+        // author's to fix, and its own `telo check` reports them.
+        if (scope !== "" && moduleDocNames.size > 0 && !moduleDocNames.has(scope))
+            continue;
+        // Dedup pipeline echoes — the same physical document emitted twice through
+        // an analyzer host's pipeline (telo studio walks a file reachable as both an
+        // entry module and an `include:` partial). Keyed on (kind, name, source,
+        // sourceLine), so two textually-distinct docs in one file keep separate
+        // fingerprints and still trip the diagnostic.
+        const meta = r.metadata;
+        const fingerprint = `${r.kind} ${name} ${meta.source} ${meta.sourceLine}`;
+        if (seen.has(fingerprint))
+            continue;
+        seen.add(fingerprint);
+        let names = byScope.get(scope);
+        if (!names)
+            byScope.set(scope, (names = new Map()));
+        const existing = names.get(name);
+        if (existing)
+            existing.push(r);
+        else
+            names.set(name, [r]);
+    }
+    for (const names of byScope.values()) {
+        for (const [name, list] of names) {
+            if (list.length <= 1)
+                continue;
+            const [first, ...rest] = list;
+            for (const dup of rest) {
+                // Two imports sharing an alias is ONE defect with its own diagnostic
+                // (`DUPLICATE_IMPORT_ALIAS`), which says what to do about it; reporting
+                // it again here would describe one mistake as two.
+                if (dup.kind === "Telo.Import" && first.kind === "Telo.Import")
+                    continue;
+                const dupMeta = dup.metadata;
+                // The precomputed range matters because editor hosts resolve positions
+                // via a `${file}::${kind}::${name}` lookup, which collides on duplicates.
+                const range = typeof dupMeta?.sourceLine === "number"
+                    ? {
+                        start: { line: dupMeta.sourceLine, character: 0 },
+                        end: { line: dupMeta.sourceLine, character: Number.MAX_SAFE_INTEGER },
+                    }
+                    : undefined;
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "DUPLICATE_RESOURCE_NAME",
+                    source: SOURCE,
+                    message: `${dup.kind}/${name}: ${describeNamed(dup, name)} collides with ` +
+                        `${describeNamed(first, name)} declared earlier — the kernel registers both ` +
+                        `under '${name}' in one namespace, so boot fails with ERR_DUPLICATE_RESOURCE. ` +
+                        `Rename one of them.`,
+                    ...(range ? { range } : {}),
+                    data: {
+                        resource: { kind: dup.kind, name },
+                        filePath: dupMeta?.source,
+                        path: "metadata.name",
+                    },
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
 /**
  * Liskov substitutability at a kind constraint: is `resolved` (a canonical
  * `<module>.<Kind>`) accepted where `targetKind` is required?
@@ -142,48 +275,24 @@ export function validateReferences(resources, context) {
     const aliasesByModule = context.aliasesByModule;
     if (!aliases || !registry)
         return diagnostics;
-    // Build outer resource lookup by name for resolution check, collecting
-    // every entry per name so we can surface name collisions as diagnostics
-    // (the kernel's resource registry shares one namespace across all
-    // non-system kinds — e.g. `Telo.Application HelloApi` and `Http.Api
-    // HelloApi` collide at boot with `ERR_DUPLICATE_RESOURCE`. Catching it
-    // statically removes a class of "everything analyzes clean, then the
-    // kernel refuses to start" surprises.)
-    //
-    // Telo.Import is excluded from the duplicate check on top of the
-    // SYSTEM_KINDS skip: its `metadata.name` is an alias, not a resource
-    // identity (aliases live in a separate namespace from resources, and
-    // colliding aliases vs. resource names is benign — the alias is only
-    // ever read as a kind prefix).
-    // Group manifests by name to detect collisions. Two subtleties:
+    // Build the outer resource lookup by name, for the resolution checks below.
+    // WHICH NAMES COLLIDE is a different question over a different namespace and
+    // is answered by `duplicateNameDiagnostics`; this map answers only "what does
+    // a bare `!ref <name>` resolve to", so it holds resolution TARGETS alone — an
+    // import alias and a kind definition are neither, and admitting them here
+    // would resolve a reference to something no ref slot can accept.
     //
-    //   1. Some analyzer hosts emit the SAME physical document twice through
-    //      their pipeline — e.g. telo studio's `toAnalysisManifests` walks
-    //      each workspace module's documents independently, and a file
-    //      reachable from two angles (entry module + `include:` partial)
-    //      shows up twice. The fingerprint includes `sourceLine` so identical
-    //      docs (same kind, name, source, AND source line) collapse to one,
-    //      while two textually-separate documents in the same file (different
-    //      source lines) keep separate fingerprints and trip the diagnostic.
-    //   2. The diagnostic carries a precomputed `range` pointing at the
-    //      duplicate's source line — editor hosts that resolve diagnostic
-    //      positions via a `${file}::${kind}::${name}` lookup would otherwise
-    //      collide on duplicates (Map.set overwrites) and place the squiggle
-    //      ambiguously. The explicit `range` short-circuits that lookup.
-    // Dedup pipeline echoes — the same physical document emitted twice
-    // through an analyzer host's pipeline. Keyed on (kind, name, source,
-    // sourceLine), so two textually-distinct docs in the same file (same
-    // source, different sourceLine) keep separate fingerprints and still
-    // trip the diagnostic. `analyze()` enforces that every non-system
-    // manifest carries both positional fields — no defensive guard needed.
+    // The list per name survives because resolution falls back to the FIRST
+    // occurrence when a collision exists, which keeps the rest of the pass
+    // behaving as it did before duplicates were reported at all.
     // Forwarded foreign exports (an imported library's exported instances, carrying a
     // metadata.module that isn't a root module) are resolution TARGETS only: excluded from
     // duplicate detection and local name resolution, and never walked as ref sources.
     const moduleOf = (r) => r.metadata?.module;
-    // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
-    // cross-module resolution targets only — excluded from duplicate detection and local name
-    // resolution, and never walked as ref sources.
-    const isForeign = (r) => r.metadata?.forwardedExport === true;
+    // A dependency's code — a forwarded export, or what extraction pulled out of one — is
+    // excluded from duplicate detection and local name resolution, and never walked as a
+    // ref source. Only an EXPORT is a cross-module resolution target.
+    const isForeign = isForwardedDeclaration;
     // Forwarded exported instances keyed `${module}\0${name}` — the lookup that resolves
     // whether a cross-module `!ref Alias.name` names a real exported instance.
     const byModuleName = new Map();
@@ -201,7 +310,7 @@ export function validateReferences(resources, context) {
                 loadedModules.add(m);
             continue;
         }
-        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r))
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForwardedExport(r))
             continue;
         const m = moduleOf(r);
         if (!m)
@@ -229,33 +338,7 @@ export function validateReferences(resources, context) {
         else
             byNameAll.set(name, [r]);
     }
-    for (const [name, list] of byNameAll) {
-        if (list.length <= 1)
-            continue;
-        const [first, ...rest] = list;
-        const firstLabel = `${first.kind}/${name}`;
-        for (const dup of rest) {
-            const dupMeta = dup.metadata;
-            const range = typeof dupMeta?.sourceLine === "number"
-                ? {
-                    start: { line: dupMeta.sourceLine, character: 0 },
-                    end: { line: dupMeta.sourceLine, character: Number.MAX_SAFE_INTEGER },
-                }
-                : undefined;
-            diagnostics.push({
-                severity: DiagnosticSeverity.Error,
-                code: "DUPLICATE_RESOURCE_NAME",
-                source: SOURCE,
-                message: `${dup.kind}/${name}: resource name collides with ${firstLabel} declared earlier (kernel runtime would fail with ERR_DUPLICATE_RESOURCE)`,
-                ...(range ? { range } : {}),
-                data: {
-                    resource: { kind: dup.kind, name },
-                    filePath: dupMeta?.source,
-                    path: "metadata.name",
-                },
-            });
-        }
-    }
+    diagnostics.push(...duplicateNameDiagnostics(resources, isForeign, moduleOf));
     // The dot rule that used to live here is now the strictest special case of
     // the identifier grammar in `validate-identifier-names.ts` — a dot is one of
     // several characters that make a name unreferenceable, and checking one of
@@ -317,6 +400,10 @@ export function validateReferences(resources, context) {
                 const target = visibleScopeManifests.find((m) => m.metadata?.name === localName) ??
                     byName.get(localName);
                 if (!target) {
+                    // A scoped name out of this declaration's reach has its own
+                    // diagnostic, which says why; this one would say only "not found".
+                    if (outsideScopesOf(r).some((scope) => scope.names.includes(localName)))
+                        return;
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
                         code: "UNRESOLVED_REFERENCE",

package/dist/validate-scope-reach.d.ts

@@ -0,0 +1,31 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * `SCOPED_NAME_OUT_OF_REACH` — a declaration written inside a scope's region but
+ * created outside the scope (see {@link OutsideScope}) naming one of the scope's
+ * resources.
+ *
+ * Written there, the name reads as reachable — the scope's names shadow the
+ * module's in its regions — while at run time it resolves to nothing, or to a
+ * module-level resource that merely shares it. Reported at the reference, in
+ * each spelling a name can be read in:
+ *
+ *  - a `!ref` sentinel, anywhere — the tag is unambiguous;
+ *  - a resolved `{kind, name}`, but ONLY where the declaring kind says a
+ *    reference is: a reference slot of its field map, or a step's dispatch slot.
+ *    An object that merely has those keys is data;
+ *  - `resources.<name>` in a CEL expression.
+ *
+ * Lexical: a scope declared on the way from the out-of-reach declaration down to
+ * the reference — found through the kinds' own scope slots — shadows the name
+ * again, since that one IS created around it. Entry-module-scoped: a
+ * dependency's code is its own analysis's to report.
+ *
+ * Browser-safe.
+ */
+export declare function validateScopedNameReach(manifests: ResourceManifest[], registry: DefinitionRegistry, aliases: AliasResolver, aliasesByModule: Map<string, AliasResolver>, rootModules: ReadonlySet<string>, 
+/** Member-access chains of a CEL expression — the analyzer's own parse. */
+accessChains: (expression: string) => string[][]): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-scope-reach.d.ts.map

package/dist/validate-scope-reach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-scope-reach.d.ts","sourceRoot":"","sources":["../src/validate-scope-reach.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAanE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAYzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3C,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC;AAChC,2EAA2E;AAC3E,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,EAAE,EAAE,GAC/C,kBAAkB,EAAE,CAyItB"}