@soda-gql/builder 0.0.9 → 0.1.0

package/dist/index.cjs

@@ -26,19 +26,20 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 let __soda_gql_common = require("@soda-gql/common");
+let node_fs = require("node:fs");
 let node_path = require("node:path");
+let node_fs_promises = require("node:fs/promises");
+let __soda_gql_core = require("@soda-gql/core");
+__soda_gql_core = __toESM(__soda_gql_core);
 let zod = require("zod");
 let neverthrow = require("neverthrow");
 let node_crypto = require("node:crypto");
 let __swc_core = require("@swc/core");
 let typescript = require("typescript");
 typescript = __toESM(typescript);
-let node_fs = require("node:fs");
 let fast_glob = require("fast-glob");
 fast_glob = __toESM(fast_glob);
 let node_vm = require("node:vm");
-let __soda_gql_core = require("@soda-gql/core");
-__soda_gql_core = __toESM(__soda_gql_core);
 let __soda_gql_runtime = require("@soda-gql/runtime");
 __soda_gql_runtime = __toESM(__soda_gql_runtime);
 
@@ -70,7 +71,11 @@ const createGraphqlSystemIdentifyHelper = (config) => {
 	const getCanonicalFileName = createGetCanonicalFileName(getUseCaseSensitiveFileNames());
 	const toCanonical = (file) => {
 		const resolved = (0, node_path.resolve)(file);
-		return getCanonicalFileName(resolved);
+		try {
+			return getCanonicalFileName((0, node_fs.realpathSync)(resolved));
+		} catch {
+			return getCanonicalFileName(resolved);
+		}
 	};
 	const graphqlSystemPath = (0, node_path.resolve)(config.outdir, "index.ts");
 	const canonicalGraphqlSystemPath = toCanonical(graphqlSystemPath);
@@ -98,6 +103,168 @@ const createGraphqlSystemIdentifyHelper = (config) => {
 	};
 };
 
+//#endregion
+//#region packages/builder/src/scheduler/effects.ts
+/**
+* File read effect - reads a file from the filesystem.
+* Works in both sync and async schedulers.
+*
+* @example
+* const content = yield* new FileReadEffect("/path/to/file").run();
+*/
+var FileReadEffect = class extends __soda_gql_common.Effect {
+	constructor(path) {
+		super();
+		this.path = path;
+	}
+	_executeSync() {
+		return (0, node_fs.readFileSync)(this.path, "utf-8");
+	}
+	_executeAsync() {
+		return (0, node_fs_promises.readFile)(this.path, "utf-8");
+	}
+};
+/**
+* File stat effect - gets file stats from the filesystem.
+* Works in both sync and async schedulers.
+*
+* @example
+* const stats = yield* new FileStatEffect("/path/to/file").run();
+*/
+var FileStatEffect = class extends __soda_gql_common.Effect {
+	constructor(path) {
+		super();
+		this.path = path;
+	}
+	_executeSync() {
+		const stats = (0, node_fs.statSync)(this.path);
+		return {
+			mtimeMs: stats.mtimeMs,
+			size: stats.size,
+			isFile: stats.isFile()
+		};
+	}
+	async _executeAsync() {
+		const stats = await (0, node_fs_promises.stat)(this.path);
+		return {
+			mtimeMs: stats.mtimeMs,
+			size: stats.size,
+			isFile: stats.isFile()
+		};
+	}
+};
+/**
+* File read effect that returns null if file doesn't exist.
+* Useful for discovery where missing files are expected.
+*/
+var OptionalFileReadEffect = class extends __soda_gql_common.Effect {
+	constructor(path) {
+		super();
+		this.path = path;
+	}
+	_executeSync() {
+		try {
+			return (0, node_fs.readFileSync)(this.path, "utf-8");
+		} catch (error) {
+			if (error.code === "ENOENT") {
+				return null;
+			}
+			throw error;
+		}
+	}
+	async _executeAsync() {
+		try {
+			return await (0, node_fs_promises.readFile)(this.path, "utf-8");
+		} catch (error) {
+			if (error.code === "ENOENT") {
+				return null;
+			}
+			throw error;
+		}
+	}
+};
+/**
+* File stat effect that returns null if file doesn't exist.
+* Useful for discovery where missing files are expected.
+*/
+var OptionalFileStatEffect = class extends __soda_gql_common.Effect {
+	constructor(path) {
+		super();
+		this.path = path;
+	}
+	_executeSync() {
+		try {
+			const stats = (0, node_fs.statSync)(this.path);
+			return {
+				mtimeMs: stats.mtimeMs,
+				size: stats.size,
+				isFile: stats.isFile()
+			};
+		} catch (error) {
+			if (error.code === "ENOENT") {
+				return null;
+			}
+			throw error;
+		}
+	}
+	async _executeAsync() {
+		try {
+			const stats = await (0, node_fs_promises.stat)(this.path);
+			return {
+				mtimeMs: stats.mtimeMs,
+				size: stats.size,
+				isFile: stats.isFile()
+			};
+		} catch (error) {
+			if (error.code === "ENOENT") {
+				return null;
+			}
+			throw error;
+		}
+	}
+};
+/**
+* Element evaluation effect - evaluates a GqlElement using its generator.
+* Supports both sync and async schedulers, enabling parallel element evaluation
+* when using async scheduler.
+*
+* @example
+* yield* new ElementEvaluationEffect(element).run();
+*/
+var ElementEvaluationEffect = class extends __soda_gql_common.Effect {
+	constructor(element) {
+		super();
+		this.element = element;
+	}
+	_executeSync() {
+		const generator = __soda_gql_core.GqlElement.createEvaluationGenerator(this.element);
+		const result = generator.next();
+		while (!result.done) {
+			throw new Error("Async operation required during sync element evaluation");
+		}
+	}
+	async _executeAsync() {
+		const generator = __soda_gql_core.GqlElement.createEvaluationGenerator(this.element);
+		let result = generator.next();
+		while (!result.done) {
+			await result.value;
+			result = generator.next();
+		}
+	}
+};
+/**
+* Builder effect constructors.
+* Extends the base Effects with file I/O operations and element evaluation.
+*/
+const BuilderEffects = {
+	...__soda_gql_common.Effects,
+	readFile: (path) => new FileReadEffect(path),
+	stat: (path) => new FileStatEffect(path),
+	readFileOptional: (path) => new OptionalFileReadEffect(path),
+	statOptional: (path) => new OptionalFileStatEffect(path),
+	evaluateElement: (element) => new ElementEvaluationEffect(element)
+};
+
 //#endregion
 //#region packages/builder/src/schemas/artifact.ts
 const BuilderArtifactElementMetadataSchema = zod.z.object({
@@ -219,7 +386,8 @@ const aggregate = ({ analyses, elements }) => {
 					operationName: element.element.operationName,
 					document: element.element.document,
 					variableNames: element.element.variableNames,
-					projectionPathGraph: element.element.projectionPathGraph
+					projectionPathGraph: element.element.projectionPathGraph,
+					metadata: element.element.metadata
 				};
 				registry.set(definition.canonicalId, {
 					id: definition.canonicalId,
@@ -237,7 +405,8 @@ const aggregate = ({ analyses, elements }) => {
 					operationType: element.element.operationType,
 					operationName: element.element.operationName,
 					document: element.element.document,
-					variableNames: element.element.variableNames
+					variableNames: element.element.variableNames,
+					metadata: element.element.metadata
 				};
 				registry.set(definition.canonicalId, {
 					id: definition.canonicalId,
@@ -959,58 +1128,41 @@ const collectAllDefinitions$1 = ({ module: module$1, gqlIdentifiers, imports: _i
 	};
 };
 /**
-* Collect diagnostics (now empty since we support all definition types)
-*/
-const collectDiagnostics$1 = () => {
-	return [];
-};
-/**
-* SWC adapter implementation
+* SWC adapter implementation.
+* The analyze method parses and collects all data in one pass,
+* ensuring the AST (Module) is released after analysis.
 */
-const swcAdapter = {
-	parse(input) {
-		const program = (0, __swc_core.parseSync)(input.source, {
-			syntax: "typescript",
-			tsx: input.filePath.endsWith(".tsx"),
-			target: "es2022",
-			decorators: false,
-			dynamicImport: true
-		});
-		if (program.type !== "Module") {
-			return null;
-		}
-		const swcModule = program;
-		swcModule.__filePath = input.filePath;
-		return swcModule;
-	},
-	collectGqlIdentifiers(file, helper) {
-		return collectGqlIdentifiers(file, helper);
-	},
-	collectImports(file) {
-		return collectImports$1(file);
-	},
-	collectExports(file) {
-		return collectExports$1(file);
-	},
-	collectDefinitions(file, context) {
-		const resolvePosition = toPositionResolver(context.source);
-		const { definitions, handledCalls } = collectAllDefinitions$1({
-			module: file,
-			gqlIdentifiers: context.gqlIdentifiers,
-			imports: context.imports,
-			exports: context.exports,
-			resolvePosition,
-			source: context.source
-		});
-		return {
-			definitions,
-			handles: handledCalls
-		};
-	},
-	collectDiagnostics(_file, _context) {
-		return collectDiagnostics$1();
+const swcAdapter = { analyze(input, helper) {
+	const program = (0, __swc_core.parseSync)(input.source, {
+		syntax: "typescript",
+		tsx: input.filePath.endsWith(".tsx"),
+		target: "es2022",
+		decorators: false,
+		dynamicImport: true
+	});
+	if (program.type !== "Module") {
+		return null;
 	}
-};
+	const swcModule = program;
+	swcModule.__filePath = input.filePath;
+	const gqlIdentifiers = collectGqlIdentifiers(swcModule, helper);
+	const imports = collectImports$1(swcModule);
+	const exports$1 = collectExports$1(swcModule);
+	const resolvePosition = toPositionResolver(input.source);
+	const { definitions } = collectAllDefinitions$1({
+		module: swcModule,
+		gqlIdentifiers,
+		imports,
+		exports: exports$1,
+		resolvePosition,
+		source: input.source
+	});
+	return {
+		imports,
+		exports: exports$1,
+		definitions
+	};
+} };
 
 //#endregion
 //#region packages/builder/src/ast/adapters/typescript.ts
@@ -1343,42 +1495,26 @@ const collectAllDefinitions = ({ sourceFile, identifiers, exports: exports$1 })
 	};
 };
 /**
-* Collect diagnostics (now empty since we support all definition types)
+* TypeScript adapter implementation.
+* The analyze method parses and collects all data in one pass,
+* ensuring the AST (ts.SourceFile) is released after analysis.
 */
-const collectDiagnostics = (_sourceFile, _identifiers, _handledCalls) => {
-	return [];
-};
-/**
-* TypeScript adapter implementation
-*/
-const typescriptAdapter = {
-	parse(input) {
-		return createSourceFile(input.filePath, input.source);
-	},
-	collectGqlIdentifiers(file, helper) {
-		return collectGqlImports(file, helper);
-	},
-	collectImports(file) {
-		return collectImports(file);
-	},
-	collectExports(file) {
-		return collectExports(file);
-	},
-	collectDefinitions(file, context) {
-		const { definitions, handledCalls } = collectAllDefinitions({
-			sourceFile: file,
-			identifiers: context.gqlIdentifiers,
-			exports: context.exports
-		});
-		return {
-			definitions,
-			handles: handledCalls
-		};
-	},
-	collectDiagnostics(file, context) {
-		return collectDiagnostics(file, context.gqlIdentifiers, context.handledCalls);
-	}
-};
+const typescriptAdapter = { analyze(input, helper) {
+	const sourceFile = createSourceFile(input.filePath, input.source);
+	const gqlIdentifiers = collectGqlImports(sourceFile, helper);
+	const imports = collectImports(sourceFile);
+	const exports$1 = collectExports(sourceFile);
+	const { definitions } = collectAllDefinitions({
+		sourceFile,
+		identifiers: gqlIdentifiers,
+		exports: exports$1
+	});
+	return {
+		imports,
+		exports: exports$1,
+		definitions
+	};
+} };
 
 //#endregion
 //#region packages/builder/src/ast/core.ts
@@ -1393,38 +1529,22 @@ const typescriptAdapter = {
 const analyzeModuleCore = (input, adapter, graphqlHelper) => {
 	const hasher = (0, __soda_gql_common.getPortableHasher)();
 	const signature = hasher.hash(input.source, "xxhash");
-	const file = adapter.parse(input);
-	if (!file) {
+	const result = adapter.analyze(input, graphqlHelper);
+	if (!result) {
 		return {
 			filePath: input.filePath,
 			signature,
 			definitions: [],
-			diagnostics: [],
 			imports: [],
 			exports: []
 		};
 	}
-	const gqlIdentifiers = adapter.collectGqlIdentifiers(file, graphqlHelper);
-	const imports = adapter.collectImports(file);
-	const exports$1 = adapter.collectExports(file);
-	const { definitions, handles } = adapter.collectDefinitions(file, {
-		gqlIdentifiers,
-		imports,
-		exports: exports$1,
-		source: input.source
-	});
-	const diagnostics = adapter.collectDiagnostics(file, {
-		gqlIdentifiers,
-		handledCalls: handles,
-		source: input.source
-	});
 	return {
 		filePath: input.filePath,
 		signature,
-		definitions,
-		diagnostics,
-		imports,
-		exports: exports$1
+		definitions: result.definitions,
+		imports: result.imports,
+		exports: result.exports
 	};
 };
 
@@ -1685,11 +1805,6 @@ const ModuleDefinitionSchema = zod.z.object({
 	loc: SourceLocationSchema,
 	expression: zod.z.string()
 });
-const ModuleDiagnosticSchema = zod.z.object({
-	code: zod.z.literal("NON_TOP_LEVEL_DEFINITION"),
-	message: zod.z.string(),
-	loc: SourceLocationSchema
-});
 const ModuleImportSchema = zod.z.object({
 	source: zod.z.string(),
 	imported: zod.z.string(),
@@ -1718,7 +1833,6 @@ const ModuleAnalysisSchema = zod.z.object({
 	filePath: zod.z.string(),
 	signature: zod.z.string(),
 	definitions: zod.z.array(ModuleDefinitionSchema).readonly(),
-	diagnostics: zod.z.array(ModuleDiagnosticSchema).readonly(),
 	imports: zod.z.array(ModuleImportSchema).readonly(),
 	exports: zod.z.array(ModuleExportSchema).readonly()
 });
@@ -1922,6 +2036,30 @@ function simpleHash(buffer) {
 	return hash.toString(16);
 }
 /**
+* Compute fingerprint from pre-read file content and stats.
+* This is used by the generator-based discoverer which already has the content.
+*
+* @param path - Absolute path to file (for caching)
+* @param stats - File stats (mtimeMs, size)
+* @param content - File content as string
+* @returns FileFingerprint
+*/
+function computeFingerprintFromContent(path, stats, content) {
+	const cached = fingerprintCache.get(path);
+	if (cached && cached.mtimeMs === stats.mtimeMs) {
+		return cached;
+	}
+	const buffer = Buffer.from(content, "utf-8");
+	const hash = computeHashSync(buffer);
+	const fingerprint = {
+		hash,
+		sizeBytes: stats.size,
+		mtimeMs: stats.mtimeMs
+	};
+	fingerprintCache.set(path, fingerprint);
+	return fingerprint;
+}
+/**
 * Invalidate cached fingerprint for a specific path
 *
 * @param path - Absolute path to invalidate
@@ -1939,11 +2077,10 @@ function clearFingerprintCache() {
 //#endregion
 //#region packages/builder/src/discovery/discoverer.ts
 /**
-* Discover and analyze all modules starting from entry points.
-* Uses AST parsing instead of RegExp for reliable dependency extraction.
-* Supports caching with fingerprint-based invalidation to skip re-parsing unchanged files.
+* Generator-based module discovery that yields effects for file I/O.
+* This allows the discovery process to be executed with either sync or async schedulers.
 */
-const discoverModules = ({ entryPaths, astAnalyzer, incremental }) => {
+function* discoverModulesGen({ entryPaths, astAnalyzer, incremental }) {
 	const snapshots = new Map();
 	const stack = [...entryPaths];
 	const changedFiles = incremental?.changedFiles ?? new Set();
@@ -1972,16 +2109,17 @@ const discoverModules = ({ entryPaths, astAnalyzer, incremental }) => {
 		if (snapshots.has(filePath)) {
 			continue;
 		}
+		let shouldReadFile = true;
 		if (invalidatedSet.has(filePath)) {
 			invalidateFingerprint(filePath);
 			cacheSkips++;
 		} else if (incremental) {
 			const cached = incremental.cache.peek(filePath);
 			if (cached) {
-				try {
-					const stats = (0, node_fs.statSync)(filePath);
-					const mtimeMs = stats.mtimeMs;
-					const sizeBytes = stats.size;
+				const stats$1 = yield* new OptionalFileStatEffect(filePath).run();
+				if (stats$1) {
+					const mtimeMs = stats$1.mtimeMs;
+					const sizeBytes = stats$1.size;
 					if (cached.fingerprint.mtimeMs === mtimeMs && cached.fingerprint.sizeBytes === sizeBytes) {
 						snapshots.set(filePath, cached);
 						cacheHits++;
@@ -1990,21 +2128,19 @@ const discoverModules = ({ entryPaths, astAnalyzer, incremental }) => {
 								stack.push(dep.resolvedPath);
 							}
 						}
-						continue;
+						shouldReadFile = false;
 					}
-				} catch {}
+				}
 			}
 		}
-		let source;
-		try {
-			source = (0, node_fs.readFileSync)(filePath, "utf8");
-		} catch (error) {
-			if (error.code === "ENOENT") {
-				incremental?.cache.delete(filePath);
-				invalidateFingerprint(filePath);
-				continue;
-			}
-			return (0, neverthrow.err)(builderErrors.discoveryIOError(filePath, error instanceof Error ? error.message : String(error)));
+		if (!shouldReadFile) {
+			continue;
+		}
+		const source = yield* new OptionalFileReadEffect(filePath).run();
+		if (source === null) {
+			incremental?.cache.delete(filePath);
+			invalidateFingerprint(filePath);
+			continue;
 		}
 		const signature = createSourceHash(source);
 		const analysis = astAnalyzer.analyze({
@@ -2018,11 +2154,8 @@ const discoverModules = ({ entryPaths, astAnalyzer, incremental }) => {
 				stack.push(dep.resolvedPath);
 			}
 		}
-		const fingerprintResult = computeFingerprint(filePath);
-		if (fingerprintResult.isErr()) {
-			return (0, neverthrow.err)(builderErrors.discoveryIOError(filePath, `Failed to compute fingerprint: ${fingerprintResult.error.message}`));
-		}
-		const fingerprint = fingerprintResult.value;
+		const stats = yield* new OptionalFileStatEffect(filePath).run();
+		const fingerprint = computeFingerprintFromContent(filePath, stats, source);
 		const snapshot = {
 			filePath,
 			normalizedFilePath: (0, __soda_gql_common.normalizePath)(filePath),
@@ -2038,12 +2171,44 @@ const discoverModules = ({ entryPaths, astAnalyzer, incremental }) => {
 			incremental.cache.store(snapshot);
 		}
 	}
-	return (0, neverthrow.ok)({
+	return {
 		snapshots: Array.from(snapshots.values()),
 		cacheHits,
 		cacheMisses,
 		cacheSkips
-	});
+	};
+}
+/**
+* Discover and analyze all modules starting from entry points.
+* Uses AST parsing instead of RegExp for reliable dependency extraction.
+* Supports caching with fingerprint-based invalidation to skip re-parsing unchanged files.
+*
+* This function uses the synchronous scheduler internally for backward compatibility.
+* For async execution with parallel file I/O, use discoverModulesGen with an async scheduler.
+*/
+const discoverModules = (options) => {
+	const scheduler = (0, __soda_gql_common.createSyncScheduler)();
+	const result = scheduler.run(() => discoverModulesGen(options));
+	if (result.isErr()) {
+		const error = result.error;
+		return (0, neverthrow.err)(builderErrors.discoveryIOError("unknown", error.message));
+	}
+	return (0, neverthrow.ok)(result.value);
+};
+/**
+* Asynchronous version of discoverModules.
+* Uses async scheduler for parallel file I/O operations.
+*
+* This is useful for large codebases where parallel file operations can improve performance.
+*/
+const discoverModulesAsync = async (options) => {
+	const scheduler = (0, __soda_gql_common.createAsyncScheduler)();
+	const result = await scheduler.run(() => discoverModulesGen(options));
+	if (result.isErr()) {
+		const error = result.error;
+		return (0, neverthrow.err)(builderErrors.discoveryIOError("unknown", error.message));
+	}
+	return (0, neverthrow.ok)(result.value);
 };
 
 //#endregion
@@ -2425,17 +2590,10 @@ const createIntermediateRegistry = ({ analyses } = {}) => {
 		}
 		return result;
 	};
-	const evaluate = () => {
-		const evaluated = new Map();
-		const inProgress = new Set();
-		for (const filePath of modules.keys()) {
-			if (!evaluated.has(filePath)) {
-				evaluateModule(filePath, evaluated, inProgress);
-			}
-		}
-		for (const element of elements.values()) {
-			__soda_gql_core.GqlElement.evaluate(element);
-		}
+	/**
+	* Build artifacts record from evaluated elements.
+	*/
+	const buildArtifacts = () => {
 		const artifacts = {};
 		for (const [canonicalId, element] of elements.entries()) {
 			if (element instanceof __soda_gql_core.Model) {
@@ -2462,6 +2620,76 @@ const createIntermediateRegistry = ({ analyses } = {}) => {
 		}
 		return artifacts;
 	};
+	/**
+	* Generator that evaluates all elements using the effect system.
+	* Uses ParallelEffect to enable parallel evaluation in async mode.
+	* In sync mode, ParallelEffect executes effects sequentially.
+	*/
+	function* evaluateElementsGen() {
+		const effects = Array.from(elements.values(), (element) => new ElementEvaluationEffect(element));
+		if (effects.length > 0) {
+			yield* new __soda_gql_common.ParallelEffect(effects).run();
+		}
+	}
+	/**
+	* Synchronous evaluation - evaluates all modules and elements synchronously.
+	* Throws if any element requires async operations (e.g., async metadata factory).
+	*/
+	const evaluate = () => {
+		const evaluated = new Map();
+		const inProgress = new Set();
+		for (const filePath of modules.keys()) {
+			if (!evaluated.has(filePath)) {
+				evaluateModule(filePath, evaluated, inProgress);
+			}
+		}
+		const scheduler = (0, __soda_gql_common.createSyncScheduler)();
+		const result = scheduler.run(() => evaluateElementsGen());
+		if (result.isErr()) {
+			throw new Error(`Element evaluation failed: ${result.error.message}`);
+		}
+		return buildArtifacts();
+	};
+	/**
+	* Asynchronous evaluation - evaluates all modules and elements with async support.
+	* Supports async metadata factories and other async operations.
+	*/
+	const evaluateAsync = async () => {
+		const evaluated = new Map();
+		const inProgress = new Set();
+		for (const filePath of modules.keys()) {
+			if (!evaluated.has(filePath)) {
+				evaluateModule(filePath, evaluated, inProgress);
+			}
+		}
+		const scheduler = (0, __soda_gql_common.createAsyncScheduler)();
+		const result = await scheduler.run(() => evaluateElementsGen());
+		if (result.isErr()) {
+			throw new Error(`Element evaluation failed: ${result.error.message}`);
+		}
+		return buildArtifacts();
+	};
+	/**
+	* Evaluate all modules synchronously using trampoline.
+	* This runs the module dependency resolution without element evaluation.
+	* Call this before getElements() when using external scheduler control.
+	*/
+	const evaluateModules = () => {
+		const evaluated = new Map();
+		const inProgress = new Set();
+		for (const filePath of modules.keys()) {
+			if (!evaluated.has(filePath)) {
+				evaluateModule(filePath, evaluated, inProgress);
+			}
+		}
+	};
+	/**
+	* Get all registered elements for external effect creation.
+	* Call evaluateModules() first to ensure all modules have been evaluated.
+	*/
+	const getElements = () => {
+		return Array.from(elements.values());
+	};
 	const clear = () => {
 		modules.clear();
 		elements.clear();
@@ -2471,6 +2699,10 @@ const createIntermediateRegistry = ({ analyses } = {}) => {
 		requestImport,
 		addElement,
 		evaluate,
+		evaluateAsync,
+		evaluateModules,
+		getElements,
+		buildArtifacts,
 		clear
 	};
 };
@@ -2604,7 +2836,11 @@ const generateIntermediateModules = function* ({ analyses, targetFiles, graphqlS
 		};
 	}
 };
-const evaluateIntermediateModules = ({ intermediateModules, graphqlSystemPath, analyses }) => {
+/**
+* Set up VM context and run intermediate module scripts.
+* Returns the registry for evaluation.
+*/
+const setupIntermediateModulesContext = ({ intermediateModules, graphqlSystemPath, analyses }) => {
 	const registry = createIntermediateRegistry({ analyses });
 	const gqlImportPath = resolveGraphqlSystemPath(graphqlSystemPath);
 	const { gql } = executeGraphqlSystemModule(gqlImportPath);
@@ -2620,10 +2856,50 @@ const evaluateIntermediateModules = ({ intermediateModules, graphqlSystemPath, a
 			throw error;
 		}
 	}
+	return registry;
+};
+/**
+* Synchronous evaluation of intermediate modules.
+* Throws if any element requires async operations (e.g., async metadata factory).
+*/
+const evaluateIntermediateModules = (input) => {
+	const registry = setupIntermediateModulesContext(input);
 	const elements = registry.evaluate();
 	registry.clear();
 	return elements;
 };
+/**
+* Asynchronous evaluation of intermediate modules.
+* Supports async metadata factories and other async operations.
+*/
+const evaluateIntermediateModulesAsync = async (input) => {
+	const registry = setupIntermediateModulesContext(input);
+	const elements = await registry.evaluateAsync();
+	registry.clear();
+	return elements;
+};
+/**
+* Generator version of evaluateIntermediateModules for external scheduler control.
+* Yields effects for element evaluation, enabling unified scheduler at the root level.
+*
+* This function:
+* 1. Sets up the VM context and runs intermediate module scripts
+* 2. Runs synchronous module evaluation (trampoline - no I/O)
+* 3. Yields element evaluation effects via ParallelEffect
+* 4. Returns the artifacts record
+*/
+function* evaluateIntermediateModulesGen(input) {
+	const registry = setupIntermediateModulesContext(input);
+	registry.evaluateModules();
+	const elements = registry.getElements();
+	const effects = elements.map((element) => new ElementEvaluationEffect(element));
+	if (effects.length > 0) {
+		yield* new __soda_gql_common.ParallelEffect(effects).run();
+	}
+	const artifacts = registry.buildArtifacts();
+	registry.clear();
+	return artifacts;
+}
 
 //#endregion
 //#region packages/builder/src/tracker/file-tracker.ts
@@ -2697,13 +2973,19 @@ const isEmptyDiff = (diff) => {
 
 //#endregion
 //#region packages/builder/src/session/dependency-validation.ts
-const validateModuleDependencies = ({ analyses }) => {
+const validateModuleDependencies = ({ analyses, graphqlSystemHelper }) => {
 	for (const analysis of analyses.values()) {
 		for (const { source, isTypeOnly } of analysis.imports) {
 			if (isTypeOnly) {
 				continue;
 			}
 			if ((0, __soda_gql_common.isRelativeSpecifier)(source)) {
+				if (graphqlSystemHelper.isGraphqlSystemImportSpecifier({
+					filePath: analysis.filePath,
+					specifier: source
+				})) {
+					continue;
+				}
 				const resolvedModule = (0, __soda_gql_common.resolveRelativeImportWithReferences)({
 					filePath: analysis.filePath,
 					specifier: source,
@@ -2839,8 +3121,11 @@ const createBuilderSession = (options) => {
 		evaluatorId
 	}));
 	const ensureFileTracker = (0, __soda_gql_common.cachedFn)(() => createFileTracker());
-	const build = (options$1) => {
-		const force = options$1?.force ?? false;
+	/**
+	* Prepare build input. Shared between sync and async builds.
+	* Returns either a skip result or the input for buildGen.
+	*/
+	const prepareBuildInput = (force) => {
 		const entryPathsResult = resolveEntryPaths(Array.from(entrypoints));
 		if (entryPathsResult.isErr()) {
 			return (0, neverthrow.err)(entryPathsResult.error);
@@ -2864,44 +3149,106 @@ const createBuilderSession = (options) => {
 			return (0, neverthrow.err)(prepareResult.error);
 		}
 		if (prepareResult.value.type === "should-skip") {
-			return (0, neverthrow.ok)(prepareResult.value.data.artifact);
+			return (0, neverthrow.ok)({
+				type: "skip",
+				artifact: prepareResult.value.data.artifact
+			});
 		}
 		const { changedFiles, removedFiles } = prepareResult.value.data;
-		const discoveryCache = ensureDiscoveryCache();
-		const astAnalyzer = ensureAstAnalyzer();
-		const discoveryResult = discover({
-			discoveryCache,
-			astAnalyzer,
-			removedFiles,
-			changedFiles,
-			entryPaths,
-			previousModuleAdjacency: state.moduleAdjacency
+		return (0, neverthrow.ok)({
+			type: "build",
+			input: {
+				entryPaths,
+				astAnalyzer: ensureAstAnalyzer(),
+				discoveryCache: ensureDiscoveryCache(),
+				changedFiles,
+				removedFiles,
+				previousModuleAdjacency: state.moduleAdjacency,
+				previousIntermediateModules: state.intermediateModules,
+				graphqlSystemPath: (0, node_path.resolve)(config.outdir, "index.ts"),
+				graphqlHelper
+			},
+			currentScan
 		});
-		if (discoveryResult.isErr()) {
-			return (0, neverthrow.err)(discoveryResult.error);
-		}
-		const { snapshots, analyses, currentModuleAdjacency, affectedFiles, stats } = discoveryResult.value;
-		const buildResult = buildDiscovered({
+	};
+	/**
+	* Finalize build and update session state.
+	*/
+	const finalizeBuild = (genResult, currentScan) => {
+		const { snapshots, analyses, currentModuleAdjacency, intermediateModules, elements, stats } = genResult;
+		const artifactResult = buildArtifact({
 			analyses,
-			affectedFiles,
-			stats,
-			previousIntermediateModules: state.intermediateModules,
-			graphqlSystemPath: (0, node_path.resolve)(config.outdir, "index.ts")
+			elements,
+			stats
 		});
-		if (buildResult.isErr()) {
-			return (0, neverthrow.err)(buildResult.error);
+		if (artifactResult.isErr()) {
+			return (0, neverthrow.err)(artifactResult.error);
 		}
-		const { intermediateModules, artifact } = buildResult.value;
 		state.gen++;
 		state.snapshots = snapshots;
 		state.moduleAdjacency = currentModuleAdjacency;
-		state.lastArtifact = artifact;
+		state.lastArtifact = artifactResult.value;
 		state.intermediateModules = intermediateModules;
-		tracker.update(currentScan);
-		return (0, neverthrow.ok)(artifact);
+		ensureFileTracker().update(currentScan);
+		return (0, neverthrow.ok)(artifactResult.value);
+	};
+	/**
+	* Synchronous build using SyncScheduler.
+	* Throws if any element requires async operations.
+	*/
+	const build = (options$1) => {
+		const prepResult = prepareBuildInput(options$1?.force ?? false);
+		if (prepResult.isErr()) {
+			return (0, neverthrow.err)(prepResult.error);
+		}
+		if (prepResult.value.type === "skip") {
+			return (0, neverthrow.ok)(prepResult.value.artifact);
+		}
+		const { input, currentScan } = prepResult.value;
+		const scheduler = (0, __soda_gql_common.createSyncScheduler)();
+		try {
+			const result = scheduler.run(() => buildGen(input));
+			if (result.isErr()) {
+				return (0, neverthrow.err)(convertSchedulerError(result.error));
+			}
+			return finalizeBuild(result.value, currentScan);
+		} catch (error) {
+			if (error && typeof error === "object" && "code" in error) {
+				return (0, neverthrow.err)(error);
+			}
+			throw error;
+		}
+	};
+	/**
+	* Asynchronous build using AsyncScheduler.
+	* Supports async metadata factories and parallel element evaluation.
+	*/
+	const buildAsync = async (options$1) => {
+		const prepResult = prepareBuildInput(options$1?.force ?? false);
+		if (prepResult.isErr()) {
+			return (0, neverthrow.err)(prepResult.error);
+		}
+		if (prepResult.value.type === "skip") {
+			return (0, neverthrow.ok)(prepResult.value.artifact);
+		}
+		const { input, currentScan } = prepResult.value;
+		const scheduler = (0, __soda_gql_common.createAsyncScheduler)();
+		try {
+			const result = await scheduler.run(() => buildGen(input));
+			if (result.isErr()) {
+				return (0, neverthrow.err)(convertSchedulerError(result.error));
+			}
+			return finalizeBuild(result.value, currentScan);
+		} catch (error) {
+			if (error && typeof error === "object" && "code" in error) {
+				return (0, neverthrow.err)(error);
+			}
+			throw error;
+		}
 	};
 	return {
 		build,
+		buildAsync,
 		getGeneration: () => state.gen,
 		getCurrentArtifact: () => state.lastArtifact,
 		dispose: () => {
@@ -2927,13 +3274,18 @@ const prepare = (input) => {
 		}
 	});
 };
-const discover = ({ discoveryCache, astAnalyzer, removedFiles, changedFiles, entryPaths, previousModuleAdjacency }) => {
+/**
+* Unified build generator that yields effects for file I/O and element evaluation.
+* This enables single scheduler control at the root level for both sync and async execution.
+*/
+function* buildGen(input) {
+	const { entryPaths, astAnalyzer, discoveryCache, changedFiles, removedFiles, previousModuleAdjacency, previousIntermediateModules, graphqlSystemPath, graphqlHelper } = input;
 	const affectedFiles = collectAffectedFiles({
 		changedFiles,
 		removedFiles,
 		previousModuleAdjacency
 	});
-	const discoveryResult = discoverModules({
+	const discoveryResult = yield* discoverModulesGen({
 		entryPaths,
 		astAnalyzer,
 		incremental: {
@@ -2943,16 +3295,16 @@ const discover = ({ discoveryCache, astAnalyzer, removedFiles, changedFiles, ent
 			affectedFiles
 		}
 	});
-	if (discoveryResult.isErr()) {
-		return (0, neverthrow.err)(discoveryResult.error);
-	}
-	const { cacheHits, cacheMisses, cacheSkips } = discoveryResult.value;
-	const snapshots = new Map(discoveryResult.value.snapshots.map((snapshot) => [snapshot.normalizedFilePath, snapshot]));
-	const analyses = new Map(discoveryResult.value.snapshots.map((snapshot) => [snapshot.normalizedFilePath, snapshot.analysis]));
-	const dependenciesValidationResult = validateModuleDependencies({ analyses });
+	const { cacheHits, cacheMisses, cacheSkips } = discoveryResult;
+	const snapshots = new Map(discoveryResult.snapshots.map((snapshot) => [snapshot.normalizedFilePath, snapshot]));
+	const analyses = new Map(discoveryResult.snapshots.map((snapshot) => [snapshot.normalizedFilePath, snapshot.analysis]));
+	const dependenciesValidationResult = validateModuleDependencies({
+		analyses,
+		graphqlSystemHelper: graphqlHelper
+	});
 	if (dependenciesValidationResult.isErr()) {
 		const error = dependenciesValidationResult.error;
-		return (0, neverthrow.err)(builderErrors.graphMissingImport(error.chain[0], error.chain[1]));
+		throw builderErrors.graphMissingImport(error.chain[0], error.chain[1]);
 	}
 	const currentModuleAdjacency = extractModuleAdjacency({ snapshots });
 	const stats = {
@@ -2960,15 +3312,6 @@ const discover = ({ discoveryCache, astAnalyzer, removedFiles, changedFiles, ent
 		misses: cacheMisses,
 		skips: cacheSkips
 	};
-	return (0, neverthrow.ok)({
-		snapshots,
-		analyses,
-		currentModuleAdjacency,
-		affectedFiles,
-		stats
-	});
-};
-const buildDiscovered = ({ analyses, affectedFiles, stats, previousIntermediateModules, graphqlSystemPath }) => {
 	const intermediateModules = new Map(previousIntermediateModules);
 	const targetFiles = new Set(affectedFiles);
 	for (const filePath of analyses.keys()) {
@@ -2991,23 +3334,29 @@ const buildDiscovered = ({ analyses, affectedFiles, stats, previousIntermediateM
 	})) {
 		intermediateModules.set(intermediateModule.filePath, intermediateModule);
 	}
-	const elements = evaluateIntermediateModules({
+	const elements = yield* evaluateIntermediateModulesGen({
 		intermediateModules,
 		graphqlSystemPath,
 		analyses
 	});
-	const artifactResult = buildArtifact({
+	return {
+		snapshots,
 		analyses,
+		currentModuleAdjacency,
+		intermediateModules,
 		elements,
 		stats
-	});
-	if (artifactResult.isErr()) {
-		return (0, neverthrow.err)(artifactResult.error);
+	};
+}
+/**
+* Convert scheduler error to builder error.
+* If the cause is already a BuilderError, return it directly to preserve error codes.
+*/
+const convertSchedulerError = (error) => {
+	if (error.cause && typeof error.cause === "object" && "code" in error.cause) {
+		return error.cause;
 	}
-	return (0, neverthrow.ok)({
-		intermediateModules,
-		artifact: artifactResult.value
-	});
+	return builderErrors.internalInvariant(error.message, "scheduler", error.cause);
 };
 
 //#endregion
@@ -3032,6 +3381,7 @@ const createBuilderService = ({ config, entrypointsOverride }) => {
 	});
 	return {
 		build: (options) => session.build(options),
+		buildAsync: (options) => session.buildAsync(options),
 		getGeneration: () => session.getGeneration(),
 		getCurrentArtifact: () => session.getCurrentArtifact(),
 		dispose: () => session.dispose()
@@ -3040,12 +3390,16 @@ const createBuilderService = ({ config, entrypointsOverride }) => {
 
 //#endregion
 exports.BuilderArtifactSchema = BuilderArtifactSchema;
+exports.BuilderEffects = BuilderEffects;
+exports.FileReadEffect = FileReadEffect;
+exports.FileStatEffect = FileStatEffect;
 Object.defineProperty(exports, 'buildAstPath', {
   enumerable: true,
   get: function () {
     return __soda_gql_common.buildAstPath;
   }
 });
+exports.collectAffectedFiles = collectAffectedFiles;
 exports.createBuilderService = createBuilderService;
 exports.createBuilderSession = createBuilderSession;
 Object.defineProperty(exports, 'createCanonicalId', {
@@ -3072,4 +3426,5 @@ Object.defineProperty(exports, 'createPathTracker', {
   get: function () {
     return __soda_gql_common.createPathTracker;
   }
-});
+});
+exports.extractModuleAdjacency = extractModuleAdjacency;