fix(typespec-ts): emit PagedAsyncIterableIterator import once at source, remove dedup workaround

resolveReference(PagingHelpers.PagedAsyncIterableIterator) left the paging iterator type unpinned, so once the generated barrels re-exported the same name the emitter could pick it up through *index.js and then rely on src/codegen/pagingImports.ts to clean up the duplicate after the fact.

This change pins PagedAsyncIterableIterator to static-helpers/pagingHelpers.js at the emission sites that write the public signatures (src/modular/helpers/operationHelpers.ts, src/codegen/operations.ts, src/codegen/classicalClient.ts, src/codegen/classicalOperations.ts) and makes the root barrel re-export point at that same concrete module (src/codegen/indexFiles.ts, src/modular/buildRootIndex.ts). With the source fixed, the post-hoc dedupe pass can be deleted entirely.

Audit: .squad/decisions/inbox/ripley-symptom-audit.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: maorleger

.squad/agents/lambert/history.md

@@ -0,0 +1,127 @@
+# Project Context
+
+- **Owner:** Maor Leger
+- **Project:** autorest.typescript — TypeSpec TS emitter refactor to align architecture with `typespec-rust` and `autorest.go` emitters.
+- **Primary reading list:**
+  - `~/workspace/emitter-chain/typespec-rust` — TypeSpec Rust emitter (the closer cousin — same TypeSpec front-end)
+  - `~/workspace/emitter-chain/autorest.go` — Go autorest generator
+  - `/home/maorleger/workspace/emitter-chain/go-rust.md` — synthesized architecture doc comparing the two. START HERE.
+- **Target codebase:** `packages/typespec-ts/src/` — especially `codemodel/` (already follows a data/render split: types.ts, build-*.ts, render-*.ts), `modular/`, `rlc/`, `framework/`, `static-helpers/`.
+- **Stack note:** TS emitter is built on the TypeSpec compiler + TCGC (@azure-tools/typespec-client-generator-core) + ts-morph for code rendering. Whatever IR pattern exists in Rust/Go needs to fit into this pipeline.
+- **Maintenance-mode:** `packages/autorest.typescript/` — do not analyze for this refactor.
+- **Created:** 2026-05-15
+
+## Learnings
+
+<!-- Append new learnings below. Each entry is something lasting about the project. -->
+
+### 2026-05-15 — TS Emitter vs Rust/Go Architecture Delta
+
+**Pipeline shape confirmed:**
+- Entry: `src/index.ts` `$onEmit()` — 500+ lines, drives everything via nested async functions
+- RLC path: `src/transform/transform.ts:43` `transformRLCModel()` is a clean TCGC→IR adapter, producing `RLCModel` from `@azure-tools/rlc-common`. This is the model to copy for Modular.
+- Modular path: NO intermediate IR. `src/modular/build*.ts` functions receive `SdkClientType<SdkServiceOperation>` (TCGC type) directly. Rendering and TCGC consumption are fused in the same function.
+- `src/codemodel/` does NOT exist (despite history.md description). It is a target location, not existing code.
+- `ContextManager` singleton at `src/contextManager.ts:41` carries: `outputProject`, `tcgcContext`, `sdkTypes`, `binder`, `dependencies`, `rlcMetaTree`, `symbolMap`.
+
+**Key citations to reuse:**
+- `src/index.ts:203` — is-modular-library branch point
+- `src/index.ts:357` — flat `for (subClient of clientMap)` loop (no recursive tree walk)
+- `src/index.ts:411–417` — final ts-morph file write loop
+- `src/transform/transform.ts:43` — `transformRLCModel()` — RLC adapter; use as pattern
+- `src/modular/buildOperations.ts:50` — `buildOperationFiles()` — imports SdkClientType directly
+- `src/modular/emitModels.ts:20–35` — imports ~10 TCGC types directly
+- `src/modular/helpers/namingHelpers.ts:13` — naming spread across helpers, no dedicated layer
+- `src/framework/hooks/sdkTypes.ts:79` — `provideSdkTypes()` — partial TCGC wrapper
+- `src/framework/hooks/binder.ts:34` — `Binder` interface — good pattern for explicit DI
+
+**Rust/Go citations confirmed:**
+- Rust adapter: `typespec-rust/packages/typespec-rust/src/tcgcadapter/adapter.ts:58` — `class Adapter`
+- Rust IR root: `typespec-rust/packages/typespec-rust/src/codemodel/crate.ts:13` — `interface Crate`
+- Rust naming: `typespec-rust/packages/typespec-rust/src/tcgcadapter/naming.ts:18` — `getEscapedReservedName`
+- Go IR root: `autorest.go/packages/codemodel.go/src/codeModel.ts:9` — `interface CodeModel`
+- Go naming: `autorest.go/packages/naming.go/src/naming.ts:9` — `getEscapedReservedName`, `ensureNameCase`
+
+**Top 3 deltas (filed to .squad/decisions/inbox/lambert-architecture-delta-v1.md):**
+1. No language-specific IR for Modular path (Rust: `Crate`, Go: `CodeModel`, TS Modular: nothing)
+2. No dedicated adapter/transform phase for Modular (TCGC leaks into every build* function)
+3. ContextManager ambient singleton vs explicit data flow / injectable DI
+
+**Impedance mismatches noted:**
+- ts-morph AST vs string builders — ts-morph is *correct* for TS emitter; intent (separation) matters, not mechanism
+- Rust trait/impl vs TS structural typing — IR should use discriminated unions (kind: "model"|"enum"|...)
+- Go `FsFacilities` injectable FS — modular path actually close to this already (in-memory Project, single write loop)
+- Go `fixStutteringTypeNames()` named pass — TS has ad-hoc `normalizeName()` calls; consolidation needed
+
+### 2026-05-15 — PR #3970 POC Findings (addendum)
+
+**PR #3970 (`origin/poc-emitter-separation`, commit `4459962`) — confirmed details:**
+- 5 new files only. Zero existing files modified. `src/index.ts` and `src/modular/buildClientContext.ts` are identical to main.
+- New dirs: `src/codemodel/index.ts` (IR), `src/tcgcadapter/adapter.ts` (adapter), `src/codegen/{emitter,clients,index}.ts` (renderer)
+- The new pipeline is NOT yet wired into `$onEmit` — pure additive infrastructure
+- Unit tests 639 pass, smoke tests pass — validates the IR shape compiles and is logically sound
+- `TSCodeModel` shape: `{ clients: TSClient[], settings: TSGenerationSettings }` — correct root
+- `TSClient` has `id`, `name`, `modularName`, `contextTypeName`, `parameters: TSClientParameter[]`, `apiVersion`, `endpoint`, `credential`, `operationGroups`, `methods`, `children`, `path`
+- Models/enums/unions are NOT yet in the IR — only client context scope covered
+- Adapter at `adapter.ts:75` — `adaptToCodeModel(input)`, `adaptSingleClient(...)` at line 94
+- Adapter reuses `src/modular/helpers/` helpers (lines 29, 30, 40–43) — pragmatic, needs migration plan
+- Codegen at `codegen/clients.ts` — `emitClientContext(project, client, settings)` — zero TCGC imports ✓
+- `useDependencies()` / `resolveReference()` still called in codegen — acceptable (narrow framework hooks, not TCGC)
+- First-stage refactor: wire `adaptSingleClient` + `emitFromCodeModel` into `index.ts` `generateModularSources()` replacing `buildClientContext()` call — one-for-one swap, integration-test validated
+
+**Key file citations:**
+- POC IR root: `packages/typespec-ts/src/codemodel/index.ts:26` — `interface TSCodeModel`
+- POC adapter entry: `packages/typespec-ts/src/tcgcadapter/adapter.ts:75` — `adaptToCodeModel()`
+- POC codegen entry: `packages/typespec-ts/src/codegen/emitter.ts:25` — `emitFromCodeModel()`
+- POC client renderer: `packages/typespec-ts/src/codegen/clients.ts:31` — `emitClientContext()`
+- Wiring target: `packages/typespec-ts/src/index.ts` around line 361 (`buildClientContext` call)
+
+### 2026-05-15 — plan.md Reconciliation (addendum)
+
+**plan.md is Maor's post-POC writeup (`poc-emitter-separation` + `poc-emitter-separation-complete`). Key takeaways:**
+
+Doubly validated (plan + go-rust.md + source):
+- Three-layer pipeline, one-pass build, directory enforcement sufficient, smoke tests as oracle, getOperationFunction() as choke point
+
+Divergences from Go/Rust (noted in pattern note §Reconciling):
+- PRD 2 self-contradiction: marked done locally, also advised against as standalone step → flag for Ripley
+- `CodeExpr = (string | SymbolRef)[]` (plan §2.2): TS-specific, correct divergence, must stay in codegen not codemodel
+- `TSTypeRef` deferred: OK but use typed discriminants (TSMethodKind, TSLroMetadata) as mitigation
+
+Critical "aspirational vs shipped" finding:
+- ALL plan.md "✅ Done" items are local only. NOTHING from PRDs 1–13 is on main. Even the index.ts wiring (PRD 1 scope item) is not committed in PR #3970.
+
+Missing from plan vs Go/Rust:
+1. Adapter type cache (Go: `Map<string, go.WireType>`) — add to PRD 7 design
+2. Named naming layer `src/tcgcadapter/naming.ts` — no PRD for this
+3. ESLint `no-restricted-imports` on `src/codegen/` and `src/codemodel/` — cheap layer guard
+4. `Readonly<TSCodeModel>` in codegen signatures — one-way flow enforcement
+
+Key plan.md citations for future reference:
+- §2.1: operationHelpers.ts 3321 LOC choke point; extractOperationShape() as fix
+- §2.2: CodeExpr pattern; resolveReference side effects
+- §2.3: refkey is process-local, not serializable → stable semantic IDs in IR
+- §2.5: addDeclaration is renderer concern; store declarationRefkey in IR
+- §2.13: full TSCodeModel needs models/enums/unions/helpers at root
+- §PRD sequence: PRD 3 → PRD 4 → PRDs 5,6,8 parallel → PRD 7 → PRDs 9,10,11 → PRD 12 → PRD 13
+
+### 2026-05-18T19:09:04.148+00:00 — PR #3981 description rewrite
+
+- Rewrote the PR title/body in Maor's voice to explain the Rust/Go-inspired three-layer migration (`tcgcadapter/` → `codemodel/` → `codegen/`), call out stages 0-6 as the current in-place swap, and explicitly list the three deferred deltas.
+
+## 2026-05-18T21:30Z — ARCHITECTURE.md for packages/typespec-ts
+Wrote `packages/typespec-ts/ARCHITECTURE.md` (~270 lines): entry-point summary,
+RLC vs Modular framing, ASCII diagram of the three-layer Modular pipeline,
+TCGC adapter / code model / codegen sections with file links, framework + static
+helpers section, two end-to-end flows (full $onEmit, single paged operation),
+testing pointer table, legacy notes, and deferred work (ContextManager singleton,
+adapter→modular/helpers coupling, missing naming.ts, codegen/models.ts still
+imports TCGC). Verified against src/index.ts, src/tcgcadapter/adapter.ts,
+src/codemodel/index.ts, src/codegen/*.ts, and CONTRIBUTING.md. Not committed —
+Maor will review and commit.
+
+### 2026-05-18T21:01:22.901+00:00 — Paging helper import must stay module-pinned
+
+- Root cause: `packages/typespec-ts/src/modular/helpers/operationHelpers.ts` emitted `PagedAsyncIterableIterator` as a free symbol in public signatures, while `packages/typespec-ts/src/codegen/indexFiles.ts` and `packages/typespec-ts/src/modular/buildRootIndex.ts` also exposed the same type through barrels. That left multiple plausible import sources and led to the post-hoc cleanup in `packages/typespec-ts/src/codegen/pagingImports.ts`.
+- Fix shape: pin the public type to `static-helpers/pagingHelpers.js` at the emission sites (`src/codegen/operations.ts`, `src/codegen/classicalClient.ts`, `src/codegen/classicalOperations.ts`) and pin barrel re-exports to the same concrete module (`src/codegen/indexFiles.ts`, `src/modular/buildRootIndex.ts`). The renderer now writes the import/export edge directly instead of asking a later sweep to guess.
+- Prior-art note: this matches the Rust/Go pattern where symbol provenance rides with the import edge rather than getting reconstructed from a barrel after the fact. In the TS emitter, the equivalent primitive is an explicit `moduleSpecifier` on the generated import/export.

.squad/decisions/inbox/lambert-paging-import-rootcause.md

@@ -0,0 +1,16 @@
+# References must carry module identity
+
+**Date:** 2026-05-18T21:01:22.901+00:00
+**Status:** Proposed
+
+## Context
+
+`packages/typespec-ts/src/codegen/pagingImports.ts` existed solely to strip `PagedAsyncIterableIterator` back out of `*index.js` imports after emission. The underlying problem was that paging signatures were emitted without a concrete module while root barrels also re-exported the same symbol, so the system had more than one valid-looking source for the same public type.
+
+## Decision
+
+References that cross files must carry module identity. If a helper or runtime symbol is meant to come from a concrete module, the emitter must write an explicit import/export edge for that module at the source emission site. Barrel resolution plus post-hoc dedupe is forbidden going forward.
+
+## Consequences
+
+When a helper type becomes part of public surface area, update the emitting renderer and any barrel re-exports together. If the current reference primitive cannot express the concrete module, extend the primitive first rather than adding another cleanup pass.

.squad/skills/module-aware-references/SKILL.md

@@ -0,0 +1,29 @@
+# Module-aware references
+
+Use this when a generated public type or helper can be imported from both a barrel and its concrete runtime/helper module.
+
+## Rule
+
+Keep symbol provenance on the import/export edge.
+
+- Emit the public signature with the concrete symbol name.
+- Add an explicit import from the concrete module in the file that owns the signature.
+- Re-export that symbol from barrels with an explicit `moduleSpecifier` pointing at the same concrete module.
+- Do not add post-hoc dedupe or text-rewrite passes.
+
+## Current example
+
+`PagedAsyncIterableIterator` now stays pinned to `static-helpers/pagingHelpers.js` in:
+- `packages/typespec-ts/src/codegen/operations.ts`
+- `packages/typespec-ts/src/codegen/classicalClient.ts`
+- `packages/typespec-ts/src/codegen/classicalOperations.ts`
+- `packages/typespec-ts/src/codegen/indexFiles.ts`
+- `packages/typespec-ts/src/modular/buildRootIndex.ts`
+
+## Checklist
+
+1. Find the first renderer that writes the public signature.
+2. Find every barrel that re-exports the same symbol.
+3. Make the renderer and barrel agree on one concrete module.
+4. Delete any cleanup pass that only exists to paper over duplicate sources.
+5. Validate with build + unit tests + the relevant integration suite.

packages/typespec-ts/src/codegen/classicalClient.ts

@@ -15,14 +15,10 @@ import type {
   TSMethod
 } from "../codemodel/index.js";
 import { resolveReference } from "../framework/reference.js";
-import { dedupePagedAsyncIterableIteratorImports } from "./pagingImports.js";
 import { refkey } from "../framework/refkey.js";
 import { useDependencies } from "../framework/hooks/useDependencies.js";
 import { AzurePollingDependencies } from "../modular/external-dependencies.js";
-import {
-  PagingHelpers,
-  SimplePollerHelpers
-} from "../modular/static-helpers-metadata.js";
+import { SimplePollerHelpers } from "../modular/static-helpers-metadata.js";
 import { getPagingLROMethodName } from "../modular/helpers/classicalOperationHelpers.js";
 
 export function emitClassicalClient(
@@ -74,6 +70,14 @@ export function emitClassicalClient(
     });
   }
 
+  if (usesPagedAsyncIterableIterator(client.methods, settings)) {
+    file.addImportDeclaration({
+      isTypeOnly: true,
+      namedImports: ["PagedAsyncIterableIterator"],
+      moduleSpecifier: "./static-helpers/pagingHelpers.js"
+    });
+  }
+
   const clientClass = file.addClass({
     isExported: true,
     name: client.name
@@ -206,11 +210,21 @@ export function emitClassicalClient(
   }
 
   file.fixMissingImports({}, { importModuleSpecifierEnding: "js" });
-  dedupePagedAsyncIterableIteratorImports(file);
   file.fixUnusedIdentifiers();
   return file;
 }
 
+function usesPagedAsyncIterableIterator(
+  methods: TSMethod[],
+  settings: TSGenerationSettings
+): boolean {
+  return methods.some(
+    (method) =>
+      method.kind === "paging" ||
+      (settings.compatibilityLro && method.kind === "lroPaging")
+  );
+}
+
 function addConstructor(
   clientClass: any,
   client: TSClient,
@@ -378,7 +392,7 @@ function buildMethodDeclarations(
       docs: [`@deprecated use ${methodName} instead`],
       kind: StructureKind.Method,
       name: normalizeName(getPagingLROMethodName(methodName), NameType.Method),
-      returnType: `${resolveReference(PagingHelpers.PagedAsyncIterableIterator)}<${method.compatibilityLroPagingReturnType ?? "void"}>`,
+      returnType: `PagedAsyncIterableIterator<${method.compatibilityLroPagingReturnType ?? "void"}>`,
       parameters,
       statements: `return ${resolveReference(method.apiRefKey)}(${[
         "this._client",

packages/typespec-ts/src/codegen/classicalOperations.ts

@@ -22,10 +22,7 @@ import { resolveReference } from "../framework/reference.js";
 import { AzurePollingDependencies } from "../modular/external-dependencies.js";
 import { getPagingLROMethodName } from "../modular/helpers/classicalOperationHelpers.js";
 import { getClassicalLayerPrefix } from "../modular/helpers/namingHelpers.js";
-import {
-  PagingHelpers,
-  SimplePollerHelpers
-} from "../modular/static-helpers-metadata.js";
+import { SimplePollerHelpers } from "../modular/static-helpers-metadata.js";
 
 interface ClassicalOperationNode {
   prefixes: string[];
@@ -56,6 +53,13 @@ export function emitClassicalOperationFiles(
       { overwrite: true }
     );
     addContextImport(file, client, node);
+    if (usesPagedAsyncIterableIterator(node.methods, settings)) {
+      file.addImportDeclaration({
+        isTypeOnly: true,
+        namedImports: ["PagedAsyncIterableIterator"],
+        moduleSpecifier: `${"../".repeat(node.prefixes.length + 1)}static-helpers/pagingHelpers.js`
+      });
+    }
     emitClassicalOperationFile(file, client, node, settings);
     file.fixMissingImports({}, { importModuleSpecifierEnding: "js" });
     file.fixUnusedIdentifiers();
@@ -65,6 +69,17 @@ export function emitClassicalOperationFiles(
   return files;
 }
 
+function usesPagedAsyncIterableIterator(
+  methods: TSMethod[],
+  settings: TSGenerationSettings
+): boolean {
+  return methods.some(
+    (method) =>
+      method.kind === "paging" ||
+      (settings.compatibilityLro && method.kind === "lroPaging")
+  );
+}
+
 function buildOperationTree(
   groups: TSOperationGroup[]
 ): ClassicalOperationNode {
@@ -270,9 +285,7 @@ function getMethodProperties(
     properties.push({
       kind: StructureKind.PropertySignature,
       name: normalizeName(getPagingLROMethodName(methodName), NameType.Method),
-      type: `(${paramStr}) => ${resolveReference(
-        PagingHelpers.PagedAsyncIterableIterator
-      )}<${method.compatibilityLroPagingReturnType ?? "void"}>`,
+      type: `(${paramStr}) => PagedAsyncIterableIterator<${method.compatibilityLroPagingReturnType ?? "void"}>`,
       docs: [`@deprecated use ${methodName} instead`]
     });
   }

packages/typespec-ts/src/codegen/indexFiles.ts

@@ -9,7 +9,6 @@ import { resolveReference } from "../framework/reference.js";
 import {
   CloudSettingHelpers,
   MultipartHelpers,
-  PagingHelpers,
   PlatformTypeHelpers
 } from "../modular/static-helpers-metadata.js";
 
@@ -298,15 +297,20 @@ function exportPagingTypes(client: TSClient, rootIndexFile: SourceFile): void {
     return;
   }
 
-  addExportsToIndex(
-    rootIndexFile,
-    [
-      resolveReference(PagingHelpers.PageSettings),
-      resolveReference(PagingHelpers.ContinuablePage),
-      resolveReference(PagingHelpers.PagedAsyncIterableIterator)
-    ],
-    true
-  );
+  const exported = new Set(rootIndexFile.getExportedDeclarations().keys());
+  const namedExports = [
+    "PageSettings",
+    "ContinuablePage",
+    "PagedAsyncIterableIterator"
+  ].filter((name) => !exported.has(name));
+
+  if (namedExports.length > 0) {
+    rootIndexFile.addExportDeclaration({
+      isTypeOnly: true,
+      moduleSpecifier: "./static-helpers/pagingHelpers.js",
+      namedExports
+    });
+  }
 }
 
 function hasPaging(client: TSClient): boolean {

packages/typespec-ts/src/codegen/operations.ts

@@ -12,10 +12,10 @@ import type {
   TSClient,
   TSFunctionDeclaration,
   TSGenerationSettings,
-  TSOperationGroup
+  TSOperationGroup,
+  TSMethod
 } from "../codemodel/index.js";
 import { addDeclaration } from "../framework/declaration.js";
-import { dedupePagedAsyncIterableIteratorImports } from "./pagingImports.js";
 
 /**
  * Emit modular operation source files from the TypeScript code model.
@@ -52,14 +52,31 @@ export function emitOperations(
       namedImports: [`${client.contextTypeName} as Client`],
       moduleSpecifier: `${indexPathPrefix}index.js`
     });
+    if (usesPagedAsyncIterableIterator(group.methods, settings)) {
+      file.addImportDeclaration({
+        isTypeOnly: true,
+        namedImports: ["PagedAsyncIterableIterator"],
+        moduleSpecifier: `../${"../".repeat(group.prefixes.length)}static-helpers/pagingHelpers.js`
+      });
+    }
     file.fixMissingImports({}, { importModuleSpecifierEnding: "js" });
-    dedupePagedAsyncIterableIteratorImports(file);
     file.fixUnusedIdentifiers();
 
     return file;
   });
 }
 
+function usesPagedAsyncIterableIterator(
+  methods: TSMethod[],
+  settings: TSGenerationSettings
+): boolean {
+  return methods.some(
+    (method) =>
+      method.kind === "paging" ||
+      (settings.compatibilityLro && method.kind === "lroPaging")
+  );
+}
+
 function getOperationGroups(client: TSClient): TSOperationGroup[] {
   const groups: TSOperationGroup[] = [];