@telorun/analyzer 1.4.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/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,CAkZtB"}
+{"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

@@ -73,11 +73,39 @@ export function validateReferences(resources, context) {
     // 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) || 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);
@@ -90,14 +118,22 @@ export function validateReferences(resources, context) {
         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: dup.metadata?.source,
+                    filePath: dupMeta?.source,
                     path: "metadata.name",
                 },
             });

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.4.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/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

@@ -85,10 +85,37 @@ export function validateReferences(
   // 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) || 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]);
@@ -98,14 +125,23 @@ export function validateReferences(
     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: (dup.metadata as { source?: string } | undefined)?.source,
+          filePath: dupMeta?.source,
           path: "metadata.name",
         },
       });

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