Execution context

type ExecutionTarget = {
	/**
	 * Application operating-system target, not the compiler host. Native builds use
	 * darwin or linux; WebAssembly uses wasi.
	 */
	readonly platform: "darwin" | "linux" | "wasi";
	/**
	 * Application architecture. Cross builds report the destination architecture.
	 */
	readonly arch: "arm64" | "x64" | "wasm32";
	/**
	 * Resolved target triple, including when --target was omitted; for example
	 * aarch64-apple-darwin.
	 */
	readonly triple: string;
};

type ExecutionOptions = {
	/**
	 * Selected application profiling instrumentation. Defaults to none; does not imply
	 * execution.production.
	 */
	readonly profile: ExecutionProfile;
};

type TestExecutionOptions = {
	/**
	 * Selected test profiling instrumentation. Defaults to none; profiling preserves
	 * command: test.
	 */
	readonly profile: ExecutionProfile;
	/**
	 * Hierarchical test-name filter from --run, or null when all discovered names are
	 * eligible.
	 */
	readonly nameFilter: string | null;
	/**
	 * Number of requested test repetitions from --repeat; defaults to 1. This is not the
	 * currently executing repetition.
	 */
	readonly repeat: number;
	/**
	 * Whether --bail stops the test run after its first failure. Defaults to false.
	 */
	readonly bail: boolean;
	/**
	 * Test callback timeout in milliseconds from --timeout. Defaults to 5000.
	 */
	readonly timeoutMs: number;
	/**
	 * Resolved positive shuffle seed, or null when shuffling is disabled. --shuffle
	 * without a seed chooses it once before compilation; the same seed drives execution
	 * and cache identity.
	 */
	readonly shuffleSeed: number | null;
};

type ExecutionEngineConfig = {
	/**
	 * Requested primordial mutation policy. Defaults to locked. The execution snapshot
	 * itself is immutable in either policy.
	 */
	readonly primordials: "locked" | "mutable";
	/**
	 * Dynamic compilation policy. false (default) rejects eval/Function execution at
	 * runtime; true enables the runtime compiler; compile-check additionally rejects
	 * statically visible dynamic compilation calls.
	 */
	readonly eval: boolean | "compile-check";
	/**
	 * Whether additional realms are enabled. Defaults to false.
	 */
	readonly realms: boolean;
	/**
	 * Whether regular expressions are enabled. Defaults to true.
	 */
	readonly regexp: boolean;
	/**
	 * Whether Temporal and its required data are enabled. Defaults to false.
	 */
	readonly temporal: boolean;
	/**
	 * Requested Intl policy after applying configuration defaults.
	 */
	readonly intl: {
		/**
		 * Whether Intl is enabled. Defaults to false.
		 */
		readonly enabled: boolean;
		/**
		 * Requested Intl service names. An empty array selects the default complete service
		 * set when Intl is enabled; it does not mean every service survived tree shaking.
		 */
		readonly features: ReadonlyArray<string>;
		/**
		 * Requested locale selection. Defaults to an empty array. Unsupported locale
		 * selections are rejected by configuration validation.
		 */
		readonly languages: ReadonlyArray<string>;
	};
};

readonly intl: {
		/**
		 * Whether Intl is enabled. Defaults to false.
		 */
		readonly enabled: boolean;
		/**
		 * Requested Intl service names. An empty array selects the default complete service
		 * set when Intl is enabled; it does not mean every service survived tree shaking.
		 */
		readonly features: ReadonlyArray<string>;
		/**
		 * Requested locale selection. Defaults to an empty array. Unsupported locale
		 * selections are rejected by configuration validation.
		 */
		readonly languages: ReadonlyArray<string>;
	};

type ExecutionConfig = {
	/**
	 * Engine configuration after validation and default resolution.
	 */
	readonly engine: ExecutionEngineConfig;
	/**
	 * Global and compatibility surface policy. maligator:process requires no enable
	 * flag.
	 */
	readonly surface: {
		/**
		 * Whether Web globals are requested. Defaults to false; native module imports are
		 * independent of this global installation policy.
		 */
		readonly webPlatform: boolean;
		/**
		 * Whether Node compatibility, globals, and node: module resolution are requested.
		 * Defaults to false.
		 */
		readonly node: boolean;
	};
	/**
	 * Resolved module-resolution policy.
	 */
	readonly modules: {
		/**
		 * Exact module-specifier replacements from configuration. Defaults to an empty
		 * object. Alias entries are immutable own data properties.
		 */
		readonly aliases: Readonly<Record<string, string>>;
	};
};

readonly surface: {
		/**
		 * Whether Web globals are requested. Defaults to false; native module imports are
		 * independent of this global installation policy.
		 */
		readonly webPlatform: boolean;
		/**
		 * Whether Node compatibility, globals, and node: module resolution are requested.
		 * Defaults to false.
		 */
		readonly node: boolean;
	};

readonly modules: {
		/**
		 * Exact module-specifier replacements from configuration. Defaults to an empty
		 * object. Alias entries are immutable own data properties.
		 */
		readonly aliases: Readonly<Record<string, string>>;
	};

type ExecutionCommon = {
	/**
	 * Explicit production application intent. True only when production was selected for
	 * the application; independent of NODE_ENV, profiling, and optimization. Currently
	 * --production is a build option. Defaults to false.
	 */
	readonly production: boolean;
	/**
	 * Whether the application image executes as native compiled code. A native
	 * executable hosting an interpreted image reports false. This is fixed for the
	 * image, not a query about the current stack frame or an eval-created function.
	 */
	readonly compiled: boolean;
	/**
	 * Actual selected frontend optimization policy. Ordinary commands currently use
	 * development; production builds and profiling use full. Backend choice is
	 * independent.
	 */
	readonly optimization: "development" | "full";
	/**
	 * Resolved application target. The compiler's host platform is not substituted
	 * during a cross build.
	 */
	readonly target: ExecutionTarget;
	/**
	 * Validated configuration policies with defaults applied, captured before
	 * compilation.
	 */
	readonly config: ExecutionConfig;
};