@telorun/analyzer 0.11.0 → 0.12.0

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA6FrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqGrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB"}

package/dist/validate-cel-context.js

@@ -94,6 +94,11 @@ export function pathMatchesScope(exprPath, scope) {
  *   `manifestRoot.provide.kind` as a kind name, looks up the kind's Telo.Definition,
  *   and returns the `outputType` schema.
  *
+ *   Accepts either a single string or an array of strings. With an array, paths
+ *   are tried in order and the first one that resolves to a usable schema wins —
+ *   used by `result:` to find its dispatch target under whichever entry-point
+ *   field (`provide:` or `invoke:`) the definition declares.
+ *
  * - `x-telo-context-ref-from`: existing form — reads `{kind, name}` object from
  *   `manifestItem.<path>`, looks up the named manifest, returns its `<subpath>` field.
  *
@@ -122,30 +127,37 @@ export function resolveContextAnnotations(schema, manifestItem, opts) {
         };
     }
     const fromRoot = schema["x-telo-context-from-root"];
-    const fromRefKind = schema["x-telo-context-from-ref-kind"];
-    if (fromRoot || fromRefKind) {
+    const fromRefKindRaw = schema["x-telo-context-from-ref-kind"];
+    const fromRefKinds = fromRefKindRaw == null
+        ? []
+        : Array.isArray(fromRefKindRaw)
+            ? fromRefKindRaw
+            : [fromRefKindRaw];
+    if (fromRoot || fromRefKinds.length > 0) {
         if (fromRoot) {
             const resolved = navigatePath(manifestRoot, fromRoot.split("/"));
             if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
                 return resolved;
             }
         }
-        if (fromRefKind && defs) {
-            const hashIdx = fromRefKind.indexOf("#");
-            if (hashIdx > 0) {
+        if (defs) {
+            for (const fromRefKind of fromRefKinds) {
+                const hashIdx = fromRefKind.indexOf("#");
+                if (hashIdx <= 0)
+                    continue;
                 const refPath = fromRefKind.slice(0, hashIdx);
                 const field = fromRefKind.slice(hashIdx + 1);
                 const kindValue = navigatePath(manifestRoot, refPath.split("/"));
-                if (typeof kindValue === "string" && kindValue.length > 0) {
-                    const canonical = aliases?.resolveKind(kindValue) ?? kindValue;
-                    const def = defs.resolve(canonical);
-                    const typeField = def
-                        ? def[field]
-                        : undefined;
-                    const resolved = resolveTypeFieldToSchema(typeField, allManifests ?? []);
-                    if (resolved && typeof resolved === "object") {
-                        return resolved;
-                    }
+                if (typeof kindValue !== "string" || kindValue.length === 0)
+                    continue;
+                const canonical = aliases?.resolveKind(kindValue) ?? kindValue;
+                const def = defs.resolve(canonical);
+                const typeField = def
+                    ? def[field]
+                    : undefined;
+                const resolved = resolveTypeFieldToSchema(typeField, allManifests ?? []);
+                if (resolved && typeof resolved === "object") {
+                    return resolved;
                 }
             }
         }

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

@@ -0,0 +1,23 @@
+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";
+/**
+ * Validates coherence rules for `Telo.Definition` documents that use the `provide:`
+ * template target, plus the implementation-presence rule on `Telo.Provider`
+ * definitions.
+ *
+ * Diagnostics:
+ *  - PROVIDE_ON_NON_PROVIDER: `provide:` declared on a definition whose
+ *    `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).
+ */
+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

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

package/dist/validate-provider-coherence.js

@@ -0,0 +1,148 @@
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Validates coherence rules for `Telo.Definition` documents that use the `provide:`
+ * template target, plus the implementation-presence rule on `Telo.Provider`
+ * definitions.
+ *
+ * Diagnostics:
+ *  - PROVIDE_ON_NON_PROVIDER: `provide:` declared on a definition whose
+ *    `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).
+ */
+export function validateProviderCoherence(manifests, registry, aliases) {
+    const diagnostics = [];
+    const importedModules = new Set();
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Import")
+            continue;
+        const resolved = m.metadata
+            ?.resolvedModuleName;
+        if (resolved)
+            importedModules.add(resolved);
+    }
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Definition")
+            continue;
+        const name = m.metadata?.name;
+        if (!name)
+            continue;
+        const ownModule = m.metadata?.module;
+        if (ownModule && importedModules.has(ownModule))
+            continue;
+        const filePath = m.metadata?.source;
+        const resource = { kind: m.kind, name };
+        const label = `${m.kind}/${name}`;
+        const md = m;
+        const capability = typeof md.capability === "string" ? md.capability : undefined;
+        const provide = md.provide;
+        const invoke = md.invoke;
+        const run = md.run;
+        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;
+        const hasControllers = Array.isArray(controllers) && controllers.length > 0;
+        if (hasProvide && capability !== "Telo.Provider") {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "PROVIDE_ON_NON_PROVIDER",
+                source: SOURCE,
+                message: `${label}: 'provide:' is only valid on definitions with 'capability: Telo.Provider' ` +
+                    `(found '${capability ?? "<unset>"}'). Use 'invoke:' or 'run:' for other capabilities.`,
+                data: { resource, filePath, path: "provide" },
+            });
+        }
+        if (hasProvide && (hasInvoke || hasRun)) {
+            const conflict = hasInvoke ? "invoke" : "run";
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "PROVIDE_DISPATCHER_CONFLICT",
+                source: SOURCE,
+                message: `${label}: 'provide:' cannot co-exist with '${conflict}:'. ` +
+                    `A definition declares exactly one dispatch entry-point.`,
+                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 (capability === "Telo.Provider" && !hasControllers && !hasProvide) {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "PROVIDER_MISSING_IMPLEMENTATION",
+                source: SOURCE,
+                message: `${label}: 'capability: Telo.Provider' requires either 'controllers:' ` +
+                    `(TS-backed) or 'provide:' (template-backed) to declare an implementation.`,
+                data: { resource, filePath, path: "capability" },
+            });
+        }
+    }
+    return diagnostics;
+}

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;AAGrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAkD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA2UtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAsbtB"}

package/dist/validate-references.js

@@ -1,13 +1,9 @@
-import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldValues } from "./reference-field-map.js";
+import { isRefSentinel } from "@telorun/templating";
+import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues } from "./reference-field-map.js";
 import { navigateJsonPointer } from "./schema-compat.js";
+import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity } from "./types.js";
 const SOURCE = "telo-analyzer";
-/** Kinds skipped by reference validation. Telo.Application and Telo.Library
- *  are intentionally not here: Application has `targets` with x-telo-ref that
- *  must be validated, and Library has no ref-bearing fields so flows through
- *  harmlessly. Telo.Import is also not here for the same reason — its
- *  `source` field isn't x-telo-ref, so nothing gets checked. */
-const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Abstract"]);
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
  * Returns an empty array when valid, or mismatch error strings when not.
@@ -64,14 +60,93 @@ export function validateReferences(resources, context) {
     const aliasesByModule = context.aliasesByModule;
     if (!aliases || !registry)
         return diagnostics;
-    // Build outer resource lookup by name for resolution check.
-    // Exclude system kinds (Telo.Definition) — they are type blueprints, not instances,
-    // and their names (e.g. "Server", "Job") would shadow user-defined resource instances.
-    const byName = new Map();
+    // 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:
+    //
+    //   1. Some analyzer hosts emit the SAME physical document twice through
+    //      their pipeline — e.g. the telo-editor'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.
+    const byNameAll = new Map();
+    const seen = new Set();
     for (const r of resources) {
-        if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind))
-            byName.set(r.metadata.name, r);
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import")
+            continue;
+        const name = r.metadata.name;
+        // `analyze()` guarantees both fields are present on non-system manifests.
+        const meta = r.metadata;
+        const fingerprint = `${r.kind} ${name} ${meta.source} ${meta.sourceLine}`;
+        if (seen.has(fingerprint))
+            continue;
+        seen.add(fingerprint);
+        const existing = byNameAll.get(name);
+        if (existing)
+            existing.push(r);
+        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",
+                },
+            });
+        }
+    }
+    // Single-resource map for the resolution / scope lookups below — when a
+    // collision exists, falling back to the first occurrence keeps the rest
+    // of the pass behaving the same as before the duplicate diagnostic was
+    // added (resolution still finds *something*; the duplicate diagnostic
+    // is what surfaces the underlying problem to the user).
+    const byName = new Map();
+    for (const [name, list] of byNameAll)
+        byName.set(name, list[0]);
     for (const r of resources) {
         if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
             continue;
@@ -119,9 +194,39 @@ export function validateReferences(resources, context) {
                     }
                 }
             }
-            for (const val of resolveFieldValues(r, fieldPath)) {
+            for (const { value: val, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
                 if (!val)
                     continue;
+                // `!ref <name>` sentinel — bare resource name marked at parse time as a
+                // reference. Look it up against the slot's x-telo-ref constraint exactly
+                // like the legacy bare-string path; the only difference is the value's
+                // shape (a TaggedSentinel rather than a raw string), which removed the
+                // string/inline ambiguity at the source.
+                if (isRefSentinel(val)) {
+                    const refName = val.source;
+                    const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+                    if (!target) {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "UNRESOLVED_REFERENCE",
+                            source: SOURCE,
+                            message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
+                            data: { resource: resourceData, filePath, path: concretePath },
+                        });
+                        continue;
+                    }
+                    const kindErrors = checkKind(target.kind, entry, registry, aliases);
+                    if (kindErrors.length > 0) {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "REFERENCE_KIND_MISMATCH",
+                            source: SOURCE,
+                            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+                            data: { resource: resourceData, filePath, path: concretePath },
+                        });
+                    }
+                    continue;
+                }
                 // Name-only reference (plain string) — look up by name to validate.
                 // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
                 // extract the resource name from the last dot segment.
@@ -142,8 +247,8 @@ export function validateReferences(resources, context) {
                             severity: DiagnosticSeverity.Error,
                             code: "UNRESOLVED_REFERENCE",
                             source: SOURCE,
-                            message: `${resourceLabel}: reference at '${fieldPath}' → resource '${val}' not found`,
-                            data: { resource: resourceData, filePath, path: fieldPath },
+                            message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
+                            data: { resource: resourceData, filePath, path: concretePath },
                         });
                         continue;
                     }
@@ -153,8 +258,8 @@ export function validateReferences(resources, context) {
                             severity: DiagnosticSeverity.Error,
                             code: "REFERENCE_KIND_MISMATCH",
                             source: SOURCE,
-                            message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-                            data: { resource: resourceData, filePath, path: fieldPath },
+                            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+                            data: { resource: resourceData, filePath, path: concretePath },
                         });
                     }
                     continue;
@@ -171,8 +276,8 @@ export function validateReferences(resources, context) {
                         severity: DiagnosticSeverity.Error,
                         code: "INVALID_REFERENCE",
                         source: SOURCE,
-                        message: `${resourceLabel}: reference at '${fieldPath}' must have string 'kind' and 'name' fields`,
-                        data: { resource: resourceData, filePath, path: fieldPath },
+                        message: `${resourceLabel}: reference at '${concretePath}' must have string 'kind' and 'name' fields`,
+                        data: { resource: resourceData, filePath, path: concretePath },
                     });
                     continue;
                 }
@@ -183,8 +288,8 @@ export function validateReferences(resources, context) {
                         severity: DiagnosticSeverity.Error,
                         code: "REFERENCE_KIND_MISMATCH",
                         source: SOURCE,
-                        message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-                        data: { resource: resourceData, filePath, path: fieldPath },
+                        message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+                        data: { resource: resourceData, filePath, path: concretePath },
                     });
                 }
                 // 3. Resolution check — resource with this name must exist.
@@ -195,8 +300,8 @@ export function validateReferences(resources, context) {
                         severity: DiagnosticSeverity.Error,
                         code: "UNRESOLVED_REFERENCE",
                         source: SOURCE,
-                        message: `${resourceLabel}: reference at '${fieldPath}' → resource '${refVal.name}' not found`,
-                        data: { resource: resourceData, filePath, path: fieldPath },
+                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${refVal.name}' not found`,
+                        data: { resource: resourceData, filePath, path: concretePath },
                     });
                 }
             }
@@ -279,7 +384,7 @@ export function validateReferences(resources, context) {
                     });
                     continue;
                 }
-                for (const fieldValue of resolveFieldValues(r, fieldPath)) {
+                for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
                     if (fieldValue == null)
                         continue;
                     const issues = registry.validateWithRefs(fieldValue, subSchema);
@@ -288,8 +393,8 @@ export function validateReferences(resources, context) {
                             severity: DiagnosticSeverity.Error,
                             code: "DEPENDENT_SCHEMA_MISMATCH",
                             source: SOURCE,
-                            message: `${resourceLabel}: '${fieldPath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
-                            data: { resource: resourceData, filePath, path: fieldPath },
+                            message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
+                            data: { resource: resourceData, filePath, path: concretePath },
                         });
                     }
                 }
@@ -309,9 +414,9 @@ export function validateReferences(resources, context) {
             const anchorValues = resolveFieldValues(r, anchorPath);
             if (anchorValues.length === 0)
                 continue; // anchor field not set — nothing to validate
-            const fieldValues = resolveFieldValues(r, fieldPath);
-            for (let i = 0; i < fieldValues.length; i++) {
-                const fieldValue = fieldValues[i];
+            const fieldEntries = resolveFieldEntries(r, fieldPath);
+            for (let i = 0; i < fieldEntries.length; i++) {
+                const { value: fieldValue, path: concretePath } = fieldEntries[i];
                 if (fieldValue == null)
                     continue;
                 // For absolute paths, the single anchor applies to all field values.
@@ -328,8 +433,8 @@ export function validateReferences(resources, context) {
                         severity: DiagnosticSeverity.Error,
                         code: "SCHEMA_FROM_MISSING_PATH",
                         source: SOURCE,
-                        message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema`,
-                        data: { resource: resourceData, filePath, path: fieldPath },
+                        message: `${resourceLabel}: x-telo-schema-from at '${concretePath}' → kind '${refVal.kind}' has no schema`,
+                        data: { resource: resourceData, filePath, path: concretePath },
                     });
                     continue;
                 }
@@ -339,8 +444,8 @@ export function validateReferences(resources, context) {
                         severity: DiagnosticSeverity.Error,
                         code: "SCHEMA_FROM_MISSING_PATH",
                         source: SOURCE,
-                        message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema path '${jsonPointer}'`,
-                        data: { resource: resourceData, filePath, path: fieldPath },
+                        message: `${resourceLabel}: x-telo-schema-from at '${concretePath}' → kind '${refVal.kind}' has no schema path '${jsonPointer}'`,
+                        data: { resource: resourceData, filePath, path: concretePath },
                     });
                     continue;
                 }
@@ -350,8 +455,8 @@ export function validateReferences(resources, context) {
                         severity: DiagnosticSeverity.Error,
                         code: "DEPENDENT_SCHEMA_MISMATCH",
                         source: SOURCE,
-                        message: `${resourceLabel}: '${fieldPath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
-                        data: { resource: resourceData, filePath, path: fieldPath },
+                        message: `${resourceLabel}: '${concretePath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
+                        data: { resource: resourceData, filePath, path: concretePath },
                     });
                 }
             }

package/dist/with-synthetic-positions.d.ts

@@ -0,0 +1,28 @@
+import type { ResourceManifest } from "@telorun/sdk";
+/**
+ * Stamp `metadata.source` and `metadata.sourceLine` on every non-system
+ * manifest that lacks them, returning a new array with cloned `metadata`
+ * objects for the affected entries.
+ *
+ * `StaticAnalyzer.analyze()` requires position info on every non-system
+ * manifest (the dedup that backs `DUPLICATE_RESOURCE_NAME` reads
+ * `(source, sourceLine)` to distinguish pipeline echoes from real
+ * collisions). Production callers — the `Loader`, `flattenForAnalyzer`,
+ * the telo-editor's `emitDocsFor`, the VSCode extension — all stamp
+ * positions already. This helper is the escape hatch for **programmatic
+ * callers** (tests, ad-hoc scripts) that construct `ResourceManifest`
+ * literals without going through a loader: it gives every otherwise-naked
+ * manifest a synthetic, deterministic position so the analyzer's
+ * invariant holds without each test having to spell positions out.
+ *
+ * The synthetic source defaults to `"<programmatic>"` — override via
+ * `source` when a stable, recognisable label helps diagnostic output.
+ * Each unstamped manifest gets a unique `sourceLine` (1-based array
+ * index) so two real duplicates supplied without positions retain
+ * distinct fingerprints and still trip `DUPLICATE_RESOURCE_NAME`.
+ *
+ * Manifests that already carry `metadata.source` and `metadata.sourceLine`
+ * pass through unchanged.
+ */
+export declare function withSyntheticPositions(manifests: ResourceManifest[], source?: string): ResourceManifest[];
+//# sourceMappingURL=with-synthetic-positions.d.ts.map

package/dist/with-synthetic-positions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-synthetic-positions.d.ts","sourceRoot":"","sources":["../src/with-synthetic-positions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,MAAM,GAAE,MAAyB,GAChC,gBAAgB,EAAE,CAgBpB"}

package/dist/with-synthetic-positions.js

@@ -0,0 +1,45 @@
+import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
+/**
+ * Stamp `metadata.source` and `metadata.sourceLine` on every non-system
+ * manifest that lacks them, returning a new array with cloned `metadata`
+ * objects for the affected entries.
+ *
+ * `StaticAnalyzer.analyze()` requires position info on every non-system
+ * manifest (the dedup that backs `DUPLICATE_RESOURCE_NAME` reads
+ * `(source, sourceLine)` to distinguish pipeline echoes from real
+ * collisions). Production callers — the `Loader`, `flattenForAnalyzer`,
+ * the telo-editor's `emitDocsFor`, the VSCode extension — all stamp
+ * positions already. This helper is the escape hatch for **programmatic
+ * callers** (tests, ad-hoc scripts) that construct `ResourceManifest`
+ * literals without going through a loader: it gives every otherwise-naked
+ * manifest a synthetic, deterministic position so the analyzer's
+ * invariant holds without each test having to spell positions out.
+ *
+ * The synthetic source defaults to `"<programmatic>"` — override via
+ * `source` when a stable, recognisable label helps diagnostic output.
+ * Each unstamped manifest gets a unique `sourceLine` (1-based array
+ * index) so two real duplicates supplied without positions retain
+ * distinct fingerprints and still trip `DUPLICATE_RESOURCE_NAME`.
+ *
+ * Manifests that already carry `metadata.source` and `metadata.sourceLine`
+ * pass through unchanged.
+ */
+export function withSyntheticPositions(manifests, source = "<programmatic>") {
+    return manifests.map((m, i) => {
+        if (REF_VALIDATION_SKIP_KINDS.has(m.kind))
+            return m;
+        const meta = m.metadata;
+        const hasSource = typeof meta?.source === "string" && meta.source.length > 0;
+        const hasLine = typeof meta?.sourceLine === "number";
+        if (hasSource && hasLine)
+            return m;
+        return {
+            ...m,
+            metadata: {
+                ...m.metadata,
+                source: hasSource ? meta.source : source,
+                sourceLine: hasLine ? meta.sourceLine : i,
+            },
+        };
+    });
+}