@telorun/analyzer 1.3.0 → 1.5.0

package/dist/analyzer.d.ts

@@ -8,6 +8,21 @@ export interface StaticAnalyzerOptions {
 export declare class StaticAnalyzer {
     private readonly celEnv;
     constructor(options?: StaticAnalyzerOptions);
+    /**
+     * Run static analysis over a flattened manifest list.
+     *
+     * **Contract**: every non-system manifest (anything outside `Telo.Definition`,
+     * `Telo.Abstract`) must carry `metadata.source` (non-empty string) and
+     * `metadata.sourceLine` (number). The dedup that backs
+     * `DUPLICATE_RESOURCE_NAME` reads those fields to tell a pipeline echo
+     * apart from a genuine collision, and downstream diagnostic positioning
+     * depends on them too. Real callers stamp positions already (the `Loader`,
+     * `flattenForAnalyzer`, the telo-editor's `emitDocsFor`, the VSCode
+     * extension). Programmatic callers — tests, ad-hoc scripts — should pass
+     * their inputs through `withSyntheticPositions(...)` before calling
+     * `analyze()`. A missing position throws a clear error rather than
+     * silently producing wrong diagnostics.
+     */
     analyze(manifests: ResourceManifest[], options?: AnalysisOptions, registry?: AnalysisRegistry): AnalysisDiagnostic[];
     analyzeErrors(manifests: ResourceManifest[], options?: AnalysisOptions, registry?: AnalysisRegistry): AnalysisDiagnostic[];
     normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[];

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAe9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA+c/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA6dvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAexF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAgB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAgf/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA8dvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAexF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -7,6 +7,7 @@ import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kerne
 import { computeSuggestKind } from "./kind-suggest.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
+import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
 import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import { celTypeSatisfiesJsonSchema, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
@@ -17,6 +18,38 @@ import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 const SELF_PREFIX = "Self.";
+/**
+ * `StaticAnalyzer.analyze()` requires `metadata.source` (non-empty) and
+ * `metadata.sourceLine` (number) on every non-system manifest — see the
+ * JSDoc on `analyze()`. Production callers stamp these via the `Loader` /
+ * `flattenForAnalyzer` / `emitDocsFor` paths; programmatic callers (tests,
+ * scripts) should pre-process inputs with `withSyntheticPositions(...)`.
+ * Surfacing the violation here turns silent dedup misbehaviour into a
+ * loud, actionable error.
+ */
+function assertManifestPositions(manifests) {
+    for (let i = 0; i < manifests.length; i++) {
+        const m = manifests[i];
+        if (REF_VALIDATION_SKIP_KINDS.has(m.kind))
+            continue;
+        const meta = m.metadata;
+        const okSource = typeof meta?.source === "string" && meta.source.length > 0;
+        const okLine = typeof meta?.sourceLine === "number";
+        if (okSource && okLine)
+            continue;
+        const label = `${m.kind}/${m.metadata?.name ?? "(unnamed)"}`;
+        const missing = [
+            !okSource ? "metadata.source" : null,
+            !okLine ? "metadata.sourceLine" : null,
+        ]
+            .filter(Boolean)
+            .join(" and ");
+        throw new Error(`StaticAnalyzer.analyze(): manifest #${i} (${label}) is missing ${missing}. ` +
+            `Real callers stamp positions automatically; programmatic callers ` +
+            `(tests, ad-hoc scripts) should pass inputs through ` +
+            `\`withSyntheticPositions(manifests)\` before calling analyze().`);
+    }
+}
 /** Resolve an alias-prefixed kind value (e.g. `Self.Encoder` or `Ai.Model`)
  *  to its canonical form. `Self.<Name>` resolves to `<ownModule>.<Name>` —
  *  the magic alias for "this library's own module" — and other prefixes
@@ -376,7 +409,23 @@ export class StaticAnalyzer {
     constructor(options = {}) {
         this.celEnv = buildCelEnvironment(options.celHandlers);
     }
+    /**
+     * Run static analysis over a flattened manifest list.
+     *
+     * **Contract**: every non-system manifest (anything outside `Telo.Definition`,
+     * `Telo.Abstract`) must carry `metadata.source` (non-empty string) and
+     * `metadata.sourceLine` (number). The dedup that backs
+     * `DUPLICATE_RESOURCE_NAME` reads those fields to tell a pipeline echo
+     * apart from a genuine collision, and downstream diagnostic positioning
+     * depends on them too. Real callers stamp positions already (the `Loader`,
+     * `flattenForAnalyzer`, the telo-editor's `emitDocsFor`, the VSCode
+     * extension). Programmatic callers — tests, ad-hoc scripts — should pass
+     * their inputs through `withSyntheticPositions(...)` before calling
+     * `analyze()`. A missing position throws a clear error rather than
+     * silently producing wrong diagnostics.
+     */
     analyze(manifests, options, registry) {
+        assertManifestPositions(manifests);
         const diagnostics = [];
         // Use pre-seeded registries from the provided AnalysisRegistry, or create fresh ones.
         // New aliases/definitions found in the manifests are accumulated into the provided instance

package/dist/definition-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition-registry.d.ts","sourceRoot":"","sources":["../src/definition-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAGlC,+EAA+E;AAC/E,qBAAa,kBAAkB;;IAK7B;;sFAEkF;IAClF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D;6DACyD;IACzD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD;;0EAEsE;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAEhE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAiC9C,OAAO,CAAC,aAAa;IASrB;;;yFAGqF;IACrF,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAgB1E;4EACwE;IACxE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMnE;wFACoF;IACpF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAWtE,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;4FAQwF;IACxF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUhD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIrD,+FAA+F;IAC/F,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIxD,gGAAgG;IAChG,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS;IAOhC;;;;;;;;qFAQiF;IACjF,2BAA2B,CACzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC1C,iBAAiB,GAAG,SAAS;IAuBhC,OAAO,CAAC,uBAAuB;IA+B/B;;qEAEiE;IACjE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAgBxD,KAAK,IAAI,MAAM,EAAE;CAGlB"}
+{"version":3,"file":"definition-registry.d.ts","sourceRoot":"","sources":["../src/definition-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAGlC,+EAA+E;AAC/E,qBAAa,kBAAkB;;IAK7B;;sFAEkF;IAClF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D;6DACyD;IACzD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD;;0EAEsE;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAEhE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAiC9C,OAAO,CAAC,aAAa;IASrB;;;yFAGqF;IACrF,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IA+B1E;4EACwE;IACxE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMnE;wFACoF;IACpF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAWtE,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;4FAQwF;IACxF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUhD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIrD,+FAA+F;IAC/F,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIxD,gGAAgG;IAChG,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS;IAOhC;;;;;;;;qFAQiF;IACjF,2BAA2B,CACzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC1C,iBAAiB,GAAG,SAAS;IAuBhC,OAAO,CAAC,uBAAuB;IA+B/B;;qEAEiE;IACjE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAgBxD,KAAK,IAAI,MAAM,EAAE;CAGlB"}

package/dist/definition-registry.js

@@ -70,6 +70,22 @@ export class DefinitionRegistry {
      *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.
      *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
     registerModuleIdentity(namespace, moduleName) {
+        // The "telo" identity is reserved for the Telo built-in module and gets
+        // populated automatically when a Telo.Abstract definition registers (see
+        // `register` below). A user app / library without a namespace must NOT
+        // claim it — silently overwriting the built-in entry breaks every
+        // x-telo-ref that resolves through "telo#…". Concretely, the
+        // `Http.Api.routes[].handler` slot in the http-server schema carries
+        // `x-telo-ref: "telo#Invocable"`. If the entry application is, say,
+        // `Telo.Application/HelloApi` (no namespace), this method previously
+        // overwrote `"telo" → "Telo"` with `"telo" → "HelloApi"`. The handler's
+        // ref then resolved to a nonexistent `HelloApi.Invocable`, the
+        // kind-mismatch check inside `validate-references.ts` short-circuited
+        // on partial context, and the analyzer reported zero issues for a
+        // manifest that explodes at runtime. Skip non-Telo no-namespace modules;
+        // they have no x-telo-ref identity to declare anyway.
+        if (!namespace && moduleName !== "Telo")
+            return;
         const identity = namespace ? `${namespace}/${moduleName}` : "telo";
         this.identityMap.set(identity, moduleName);
         this.reverseIdentityMap.set(moduleName, identity);

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { buildDocumentPositions, buildLineOffsets, buildPositionIndex, documentL
 export type { DocumentPosition } from "./position-metadata.js";
 export { HttpSource } from "./sources/http-source.js";
 export { RegistrySource } from "./sources/registry-source.js";
+export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type { AnalysisDiagnostic, AnalysisOptions, LoaderInitOptions, LoadOptions, ManifestSource, Position, PositionIndex, Range } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACR,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EACH,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC3E,YAAY,EACR,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,aAAa,EACb,KAAK,EACR,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACR,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EACH,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC3E,YAAY,EACR,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,aAAa,EACb,KAAK,EACR,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -8,4 +8,5 @@ export { residualEntrySchema, residualEntrySchemaMap } from "./residual-schema.j
 export { buildDocumentPositions, buildLineOffsets, buildPositionIndex, documentLineOffsets, } from "./position-metadata.js";
 export { HttpSource } from "./sources/http-source.js";
 export { RegistrySource } from "./sources/registry-source.js";
+export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";

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;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,CA2WtB"}
+{"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

@@ -60,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;

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,
+            },
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",

package/src/analyzer.ts

@@ -14,6 +14,7 @@ import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kerne
 import { computeSuggestKind } from "./kind-suggest.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
+import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
 import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import {
@@ -36,6 +37,39 @@ import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
 const SELF_PREFIX = "Self.";
 
+/**
+ * `StaticAnalyzer.analyze()` requires `metadata.source` (non-empty) and
+ * `metadata.sourceLine` (number) on every non-system manifest — see the
+ * JSDoc on `analyze()`. Production callers stamp these via the `Loader` /
+ * `flattenForAnalyzer` / `emitDocsFor` paths; programmatic callers (tests,
+ * scripts) should pre-process inputs with `withSyntheticPositions(...)`.
+ * Surfacing the violation here turns silent dedup misbehaviour into a
+ * loud, actionable error.
+ */
+function assertManifestPositions(manifests: ResourceManifest[]): void {
+  for (let i = 0; i < manifests.length; i++) {
+    const m = manifests[i];
+    if (REF_VALIDATION_SKIP_KINDS.has(m.kind)) continue;
+    const meta = m.metadata as { source?: string; sourceLine?: number } | undefined;
+    const okSource = typeof meta?.source === "string" && meta.source.length > 0;
+    const okLine = typeof meta?.sourceLine === "number";
+    if (okSource && okLine) continue;
+    const label = `${m.kind}/${m.metadata?.name ?? "(unnamed)"}`;
+    const missing = [
+      !okSource ? "metadata.source" : null,
+      !okLine ? "metadata.sourceLine" : null,
+    ]
+      .filter(Boolean)
+      .join(" and ");
+    throw new Error(
+      `StaticAnalyzer.analyze(): manifest #${i} (${label}) is missing ${missing}. ` +
+        `Real callers stamp positions automatically; programmatic callers ` +
+        `(tests, ad-hoc scripts) should pass inputs through ` +
+        `\`withSyntheticPositions(manifests)\` before calling analyze().`,
+    );
+  }
+}
+
 /** Resolve an alias-prefixed kind value (e.g. `Self.Encoder` or `Ai.Model`)
  *  to its canonical form. `Self.<Name>` resolves to `<ownModule>.<Name>` —
  *  the magic alias for "this library's own module" — and other prefixes
@@ -496,11 +530,27 @@ export class StaticAnalyzer {
     this.celEnv = buildCelEnvironment(options.celHandlers);
   }
 
+  /**
+   * Run static analysis over a flattened manifest list.
+   *
+   * **Contract**: every non-system manifest (anything outside `Telo.Definition`,
+   * `Telo.Abstract`) must carry `metadata.source` (non-empty string) and
+   * `metadata.sourceLine` (number). The dedup that backs
+   * `DUPLICATE_RESOURCE_NAME` reads those fields to tell a pipeline echo
+   * apart from a genuine collision, and downstream diagnostic positioning
+   * depends on them too. Real callers stamp positions already (the `Loader`,
+   * `flattenForAnalyzer`, the telo-editor's `emitDocsFor`, the VSCode
+   * extension). Programmatic callers — tests, ad-hoc scripts — should pass
+   * their inputs through `withSyntheticPositions(...)` before calling
+   * `analyze()`. A missing position throws a clear error rather than
+   * silently producing wrong diagnostics.
+   */
   analyze(
     manifests: ResourceManifest[],
     options?: AnalysisOptions,
     registry?: AnalysisRegistry,
   ): AnalysisDiagnostic[] {
+    assertManifestPositions(manifests);
     const diagnostics: AnalysisDiagnostic[] = [];
 
     // Use pre-seeded registries from the provided AnalysisRegistry, or create fresh ones.

package/src/definition-registry.ts

@@ -80,6 +80,21 @@ export class DefinitionRegistry {
    *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.
    *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
   registerModuleIdentity(namespace: string | null, moduleName: string): void {
+    // The "telo" identity is reserved for the Telo built-in module and gets
+    // populated automatically when a Telo.Abstract definition registers (see
+    // `register` below). A user app / library without a namespace must NOT
+    // claim it — silently overwriting the built-in entry breaks every
+    // x-telo-ref that resolves through "telo#…". Concretely, the
+    // `Http.Api.routes[].handler` slot in the http-server schema carries
+    // `x-telo-ref: "telo#Invocable"`. If the entry application is, say,
+    // `Telo.Application/HelloApi` (no namespace), this method previously
+    // overwrote `"telo" → "Telo"` with `"telo" → "HelloApi"`. The handler's
+    // ref then resolved to a nonexistent `HelloApi.Invocable`, the
+    // kind-mismatch check inside `validate-references.ts` short-circuited
+    // on partial context, and the analyzer reported zero issues for a
+    // manifest that explodes at runtime. Skip non-Telo no-namespace modules;
+    // they have no x-telo-ref identity to declare anyway.
+    if (!namespace && moduleName !== "Telo") return;
     const identity = namespace ? `${namespace}/${moduleName}` : "telo";
     this.identityMap.set(identity, moduleName);
     this.reverseIdentityMap.set(moduleName, identity);

package/src/index.ts

@@ -24,6 +24,7 @@ export {
 export type { DocumentPosition } from "./position-metadata.js";
 export { HttpSource } from "./sources/http-source.js";
 export { RegistrySource } from "./sources/registry-source.js";
+export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type {
     AnalysisDiagnostic,

package/src/validate-references.ts

@@ -72,13 +72,88 @@ export function validateReferences(
   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<string, ResourceManifest>();
+  // 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<string, ResourceManifest[]>();
+  const seen = new Set<string>();
   for (const r of resources) {
-    if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) byName.set(r.metadata.name as string, r);
+    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import") continue;
+    const name = r.metadata.name as string;
+    // `analyze()` guarantees both fields are present on non-system manifests.
+    const meta = r.metadata as unknown as { source: string; sourceLine: number };
+    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 as { source?: string; sourceLine?: number } | undefined;
+      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<string, ResourceManifest>();
+  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;

package/src/with-synthetic-positions.ts

@@ -0,0 +1,48 @@
+import type { ResourceManifest } from "@telorun/sdk";
+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: ResourceManifest[],
+  source: string = "<programmatic>",
+): ResourceManifest[] {
+  return manifests.map((m, i) => {
+    if (REF_VALIDATION_SKIP_KINDS.has(m.kind)) return m;
+    const meta = m.metadata as { source?: string; sourceLine?: number } | undefined;
+    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,
+      },
+    } as ResourceManifest;
+  });
+}