diff --git a/README.md b/README.md
index de25e2c77..da4365101 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,9 @@ the [Kotlin Source Code Repository](https://github.com/JetBrains/kotlin).
 ## Current KEEPs
 
 * Current in-progress KEEPs are listed in [issues](https://github.com/Kotlin/KEEP/issues).
+  Each KEEP is assigned an ID. KEEP ID is the same as issue ID
 * New KEEPs and additions to current KEEPs are submitted as [pull requests](https://github.com/Kotlin/KEEP/pulls).
+  Every KEEP file name must be prefixed with the KEEP ID
 * When KEEPs are implemented, the corresponding design documents are merged into this repository and stored in a [proposals](proposals) directory.
 
 ### Design notes
diff --git a/proposals/type-aliases.md b/proposals/KEEP-0004-type-aliases.md
similarity index 100%
rename from proposals/type-aliases.md
rename to proposals/KEEP-0004-type-aliases.md
diff --git a/proposals/bound-callable-references.md b/proposals/KEEP-0005-bound-callable-references.md
similarity index 100%
rename from proposals/bound-callable-references.md
rename to proposals/KEEP-0005-bound-callable-references.md
diff --git a/proposals/local-delegated-properties.md b/proposals/KEEP-0025-local-delegated-properties.md
similarity index 100%
rename from proposals/local-delegated-properties.md
rename to proposals/KEEP-0025-local-delegated-properties.md
diff --git a/proposals/sealed-class-inheritance.md b/proposals/KEEP-0029-sealed-class-inheritance.md
similarity index 100%
rename from proposals/sealed-class-inheritance.md
rename to proposals/KEEP-0029-sealed-class-inheritance.md
diff --git a/proposals/jdk-dependent-built-ins.md b/proposals/KEEP-0030-jdk-dependent-built-ins.md
similarity index 100%
rename from proposals/jdk-dependent-built-ins.md
rename to proposals/KEEP-0030-jdk-dependent-built-ins.md
diff --git a/proposals/data-class-inheritance.md b/proposals/KEEP-0031-data-class-inheritance.md
similarity index 100%
rename from proposals/data-class-inheritance.md
rename to proposals/KEEP-0031-data-class-inheritance.md
diff --git a/proposals/destructuring-in-parameters.md b/proposals/KEEP-0032-destructuring-in-parameters.md
similarity index 100%
rename from proposals/destructuring-in-parameters.md
rename to proposals/KEEP-0032-destructuring-in-parameters.md
diff --git a/proposals/inline-properties.md b/proposals/KEEP-0034-inline-properties.md
similarity index 100%
rename from proposals/inline-properties.md
rename to proposals/KEEP-0034-inline-properties.md
diff --git a/proposals/explicit-api-mode.md b/proposals/KEEP-0045-explicit-api-mode.md
similarity index 100%
rename from proposals/explicit-api-mode.md
rename to proposals/KEEP-0045-explicit-api-mode.md
diff --git a/proposals/underscore-for-unused-parameters.md b/proposals/KEEP-0055-underscore-for-unused-parameters.md
similarity index 100%
rename from proposals/underscore-for-unused-parameters.md
rename to proposals/KEEP-0055-underscore-for-unused-parameters.md
diff --git a/proposals/scope-control-for-implicit-receivers.md b/proposals/KEEP-0057-scope-control-for-implicit-receivers.md
similarity index 100%
rename from proposals/scope-control-for-implicit-receivers.md
rename to proposals/KEEP-0057-scope-control-for-implicit-receivers.md
diff --git a/proposals/underscores-in-numeric-literals.md b/proposals/KEEP-0059-underscores-in-numeric-literals.md
similarity index 100%
rename from proposals/underscores-in-numeric-literals.md
rename to proposals/KEEP-0059-underscores-in-numeric-literals.md
diff --git a/proposals/generic-values-and-valueof-for-enums.md b/proposals/KEEP-0061-generic-values-and-valueof-for-enums.md
similarity index 100%
rename from proposals/generic-values-and-valueof-for-enums.md
rename to proposals/KEEP-0061-generic-values-and-valueof-for-enums.md
diff --git a/proposals/KEEP-0075-scripting-support.md b/proposals/KEEP-0075-scripting-support.md
new file mode 100644
index 000000000..7903582e6
--- /dev/null
+++ b/proposals/KEEP-0075-scripting-support.md
@@ -0,0 +1,895 @@
+
+# Kotlin Scripting support
+
+*Replaces [Script Definition Template](https://github.com/Kotlin/KEEP/blob/master/proposals/script-definition-template.md)
+proposal.*
+
+## Feedback
+
+Discussion of this proposal is held in [this issue](https://github.com/Kotlin/KEEP/issues/75)
+
+## Motivation
+
+- Define Kotlin scripting and its applications
+- Describe intended use cases for the Kotlin scripting
+- Define scripting support that is: 
+  - applicable to all Kotlin platforms
+  - provides sufficient control of interpretation and execution of scripts
+  - simple enough to configure and customize
+  - provides usable default components and configurations for the typical use cases    
+- Provide basic examples of the scripting usage and implementation
+- Address the issues found during the public usage of the current scripting support 
+
+## Status of this document
+
+The document is still a draft, and few important parts are still missing, in particular:
+
+- REPL:
+  - API for REPL host configuration and embedding
+  - API for REPL plugins (maybe should be covered elsewhere):
+    - custom repl commands
+    - highlighting
+    - completion
+    - etc.
+- IDE plugins API for custom scripting support (besides discovery)
+
+## Table of contents
+
+- [Applications](#applications)
+- [Basic definitions](#basic-definitions)
+- [Use cases](#use-cases)
+  - [Embedded scripting](#embedded-scripting)
+  - [Standalone scripting](#standalone-scripting)
+  - [Project infrastructure scripting](#project-infrastructure-scripting)
+  - [Script-based DSL](#script-based-dsl)
+- [Proposal](#proposal)
+  - [Architecture](#architecture)
+  - [Script definition](#script-definition)
+  - [Script Compilation](#script-compilation)
+  - [Script Evaluation](#script-evaluation)
+  - [Standard hosts and discovery](#standard-hosts-and-discovery)
+  - [How to implement scripting support](#how-to-implement-scripting-support)
+  - [Implementation status](#implementation-status)
+  - [Examples](#examples)
+    - [kotlin-main-kts](#kotlin-main-kts)
+
+## Applications
+
+- Build scripts (Gradle/Kobalt)
+- Test scripts (Spek)
+- Command-line utilities
+- Routing scripts (ktor)
+- Type-safe configuration files (TeamCity)
+- In-process scripting and REPL for IDE
+- Consoles like IPython/Jupyter Notebook
+- Game scripting engines
+- ...
+
+## Basic definitions
+
+- **Script** - a text file written in Kotlin language but allowing top-level statements and expressions and having access 
+  to some implicit (not directly mentioned in the script text) properties, functions and objects, as if the whole script 
+  body is a body of an implicit function placed in some environment (see below)
+- **Scripting Host** - an application or a component which handles script execution   
+- **Scripting Host Environment** - a set of parameters that defines an environment for all scripting host services,
+  contains when relevant: project paths, jdk path, etc. It is passed on constructing the services     
+- **REPL snippet** - a group of script text lines, executed in a single REPL eval call
+- **Script compilation configuration** - a set of parameters configuring script compilation, such as dependencies,
+  external variables declarations, implicit import statements, etc. 
+- **Script evaluation configuration** - a set of parameters configuring script evaluation, such as external variables 
+  instances, actual script parameters, etc. 
+- **Script definition** - a set of parameters and configurations defining a script type   
+- **Compiled script** - a binary compiled code of the script, stored in memory or on disk, which could be loaded 
+  and instantiated by appropriate platform
+- **Dependency** - an external library or another project whose declarations are available for the script being compiled 
+  and evaluated
+- **Imported script** - another script whose declarations are available for the script being compiled and evaluated
+- **Configuration refinement** - the process of updating script compilation and evaluation configurations during 
+  compilation/evaluation with parameter specific to the particular script exemplar, e.g. depending on the script 
+  contents
+
+## Use cases
+
+### Embedded scripting
+
+The use case when a scripting host is embedded into user's application, e.g. specialized console like 
+IPython/Jupyter notebook, Spark shell, embedded game scripting, IDE and other application-level scripting. 
+
+#### Environment and customization
+
+In this case the script is most likely need to run in a specific execution environment, defined by the scripting host. 
+The default script compilation and evaluation configurations are defined by the scripting host as well. The host may 
+provide script authors with a possibility to customize some configuration parameters, e.g. to add dependencies or 
+specify additional compilation options, e.g. using annotations in the script text:
+
+```kt
+@file:DependsOn("maven:artifact:1.0", "imported.package.*")
+@file:Import("path/to/externalScript.kts")
+@file:CompilerOptions("-someCompilerOpt")
+```
+
+To implement this the compilation/evaluation pipeline should provide a callback mechanism to call a host-provided code 
+that could analyze script text directly or parsed annotations in order to update compilation and evaluation 
+configurations with parameters depending on the script contents or other dynamic factors.
+
+If the host need to support several script *types*, i.e. sets of compilation configurations and customization means, 
+there should be a way for the host to distinguish the scripts and select appropriate set of 
+compilation/configuration/evaluation services and properties. The host authors can implement the selection based on any 
+script property, but due to the difficulties in supporting file type distinction based on anything but filename 
+extension across platforms and IDEs, the default implementations should support only extension-based or file name based 
+selection.     
+
+*Note: It would be nice to provide an infrastructure (complete hosts or libraries) that support some typical mean for 
+each platform to resolve external libraries from online repositories (e.g. - maven for JVM) out of the box.*
+
+#### Typical usages
+
+In a simple case, the developer wants to implement a scripting host to control script execution and provide the required 
+environment. One may want to write something as simple as:
+```kt
+KotlinScriptingHost().eval(File("path/to/script.kts"))
+```
+or
+```kt
+KotlinScriptingHost().eval("println(\"Hello from script!\")")
+```
+and the script should be executed in the current environment with some reasonable default compilation and evaluation 
+settings. If things need to be configured explicitly, the code would look like:
+```kt
+val scriptingHost = KotlinScriptingHost(configurationParams...)
+scriptingHost.eval(File("path/to/script.kts"), compilationConfiguration, evaluationConfiguration)
+```
+This would also allow the developer to control the lifetime of the scripting host.
+
+In cases then there is more control needed for the compilation and evaluation process, the direct use of the script
+compiler and evaluator could be desirable:
+```kt
+val scriptCompiler = KotlinScriptCompiler(configurationParams...)
+val compiledScript = scriptCompiler.invoke(File("path/to/script.kts"), compilationConfiguration)
+val scriptEvaluator = KotlinScriptEvaluator(configurationParams...)
+val evaluationResult = scriptEvaluator.invoke(compiledScript, evaluationConfiguration)
+```
+In addition in this case the compiled script could be evaluated more than once.
+
+#### More control
+
+To be able to run scripts in a user controlled environment, the following information bits could be configured or 
+provided to the host: 
+- *Script Compiler* - the service that will compile scripts into a form accepted by the Evaluator
+- *Script Compilation Configuration* - set of properties defining the script compilation settings, including:
+  - *Script Base Class* - an interface (or prototype) of the script class, expected by the executor, so the compiler
+    should compile script into the appropriate class
+  - *Dependencies* - external libraries that could be used in the script
+  - *Default imports* - import statements implicitly added to any compiled script
+  - *Provided properties* - properties with types that is assumed visible in the script scope
+  - etc.
+- *Script Evaluator* - the service that will actually evaluate the compiled scripts in the required execution 
+  environment
+- *Evaluation configuration* - set of properties defining an environment for the evaluation, including:
+  - *Provided properties* - actual values of the provided properties from the compilation configuration
+  - etc. 
+  
+Some of these parameters could be wrapped into a *Script Definition* for easier identification of the script types
+by the hosts that may support handling of the several script types simultaneously. 
+  
+#### Caching
+
+Since calling Kotlin compiler could be quite a heavy operation in comparison with typical script execution, the caching
+of the compiled script should be supported by the compilation platform.
+
+#### Execution lifecycle
+
+The script is executed according to the following scheme:
+- compilation - the *Script Compiler* takes the script, its compilation configuration and 
+  provides a compiled class. Inside this process. If the compilation configuration defines refinement callbacks, they 
+  are called before or after parsing to update configuration with parameter depending on the script contents or other
+  dynamic data.
+- evaluation - the *Script Evaluator* takes the compiled script instantiates it if needed, and calls the appropriate 
+  method, passing arguments from the environment to it; this step could be repeated many times. If evaluation 
+  configuration defines refinement callbacks, they will be called before evaluation similarly to the compilation ones.
+  
+#### Processing in an IDE
+
+The IDE support for the scripts should be based on the same *Script definition*. Basically after recognizing the script
+*type* (see *Environment and customization* section above), the IDE extracts the *Compilation Configuration* and use its 
+parameters to implement highlighting, navigation and other features. The default implementation of Kotlin IDEA plugin
+should support the appropriate functionality, based on the standard set of configuration parameters.
+
+### Standalone scripting
+
+Standalone scripting applications include command-line utilities and a standalone Kotlin REPL.
+
+Standalone scripting is a variant of the embedded scripting with hosts provided with the Kotlin distribution or 
+3rd-party hosts.
+
+#### Hosts
+
+The standalone script could be executed e.g. using command line Kotlin compiler:
+
+```sh
+kotlinc -cp <classpath required by the script definition> -script myscript.kts
+```
+
+Or with the dedicated runner included into the distribution:
+
+```sh
+kotlin -cp <classpath required by the script definition> myscript.kts
+```
+
+To be able to use the Kotlin scripts in a Unix shell environment, the *shebang* (`#!`) syntax should be supported 
+at the beginning of the script:
+```sh
+#! /path/to/kotlin/script/runner -some -params
+```
+
+*Note: due to lack of clear specification, passing parameters in the shebang line could be 
+[problematic](https://stackoverflow.com/questions/4303128/how-to-use-multiple-arguments-with-a-shebang-i-e/4304187#4304187), 
+therefore alternative schemes of configuring scripts should be available.*
+
+#### Script customizations
+
+It should be possible to process custom scripts with the standard hosts, e.g. by supplying a custom script definition 
+in the command line, e.g.:
+```sh
+kotlin -script-templates="org.acme.MyScriptDef" -cp myScriptDefLib.jar myscript.myscr.kts
+```
+In this case the host loads specified definition class, and extract required definition from it and its annotations.
+
+Another possible mechanism is automatic discovery, simplifying usage:
+```sh
+kotlin -cp myScriptDefLib.jar myscript.myscr.kts
+```
+In this case the host analyses the classpath, discovers script definitions located there and then processes then as 
+before. Note that in this case it is should be recommended to use dedicated script extension (`myscr.kts`) in every 
+definition to minimize chances of clashes if several script definitions will appear in the classpath. And on top of
+that, some selection mechanism based on the file names and/or paths is needed, e.g. to cover cases like gradle's 
+`build.gradle.kts` and `setting.gradle.kts` that should be treated like different script types.
+
+#### Script parameters
+
+For the command line usage the support for script parameters is needed. The simplest form is to assume that the script
+has access to the `args: Array<String>` property/parameter. More advanced is to have a customization that supports a 
+declaration of the typed parameters in the script annotations e.g.:
+
+```kt
+@file:param("name", "String?") // note: stringified types are used for the cases not supported by class literals
+@file:param("num", Int::class)  
+@file:param("list", "List<String>") 
+
+// this script could be called with args "-name=abc -num=42 -list=a,b,c" 
+// and then in the body we can access parsed typed arguments
+
+println("${name ?: "<unknown>"} ${num/6}: ${list.map { it.toUpperCase() } }") 
+```
+
+#### IDE support
+
+Since in this use case scripts are not part of any project, support for such script should be configured in the IDE
+explicitly, either via a plugin or via the IDE settings.
+
+#### Standalone REPL
+
+Standalone REPL is invoked by a dedicated host the same way as for standalone script but accepts user's input as repl 
+snippets. It means that the declarations made in the previous snippets are accessible in the subsequent ones.  
+In this mode, all new scripting features should be accessible as well, including customization.
+
+### Project infrastructure scripting
+
+Applications: project-level REPL, build scripts, source generation scripts, etc.
+ 
+Project infrastructure scripts are executed by some dedicated scripting host usually embedded into the project build 
+system. So it is a variant of the embedded scripting with the host and the IDE support integrated into build system 
+and/or IDE itself.
+
+#### IDE support
+
+From an IDE point of view, they are project-context dependent, but may not be part of the project sources. (In the same 
+sense as e.g. gradle build scripts source is not considered as a part of the project sources.) In this case the support
+in the IDE is possible only if the definitions are supplied to the IDE explicitly, similarly to standalone scripts,
+either via a plugin or via the IDE settings.
+
+#### Discovery
+
+The IDE needs to be able to extract scripts environment configurations from the project settings, if the scrips are 
+considered a part of the project sources, so the project's classpath could be used for discovery of the supported 
+scripts.
+ 
+#### Project-level REPL
+ 
+A REPL that has access to the project's compiled classes.
+
+### Script-based DSL
+
+Applications: test definition scripts (Spek), routing scripts (ktor), type safe config files, etc.
+ 
+In these cases the scripts are considered parts of the kotlin project and are compiled to appropriate binary form by the 
+compiler, and then linked with the rest of the compilation results. They differ from the other project's sources by the 
+possibility to employ script semantic and configurability and therefore avoid some boilerplate and make the sources 
+look more DSL-like.
+ 
+In this scenario, no dedicated scripting host is used, but the standard compiler is used during the regular compilation 
+according to configured script recognition logic (e.g. the script type discovery mechanism described above), and the 
+target application should implement its own logic for instantiating and calling the generated script classes.  
+Script compiler may also annotate generated classes and methods with user-specified annotations to integrate it with 
+existing execution logic. E.g. junit test scripts could be annotated accordingly.
+
+From an IDE point of view, these scripts are the part of the project but should be configured according to the 
+recognized script definition.
+
+## Proposal
+
+### Architecture
+
+#### Components
+
+The scripting support consists of the following components:
+- `ScriptCompiler` - interface for script compilation
+  - compilation: `(scriptSource, compilationConfiguration) -> compiledScript`
+  - predefined script compilers based on the kotlin platforms: /JVM, /JS, /Native
+  - custom/customized implementation possible
+  - compiled scripts caсhing belongs here
+  - should not keep the state of the script compilation, the required state for the subsequent compilations, e.g. in the 
+    REPL mode, is passed along with the compiled script
+- `ScriptEvaluator` - the component that receives compiled script instantiates it, and then evaluates it in a required 
+  environment, supplying any arguments that the script requires:
+  - evaluation: `(compiledScript, evaluationConfiguration) -> Any?`
+  - the `compiledScript` contains the final compilation configuration used
+  - the `evaluationConfiguration` the parameters describing the actual script evaluation configuration of the script
+  - predefined platform-specific evaluators available, but could be provided by the scripting host
+  - pseudo-evaluators that save compiled script into e.g. an executable jar should be provided as well
+- **IDE support** - Kotlin IDEA plugin should have support for scripting with script definition selection based on the 
+  file name extension, and also includes discovery. The exposed generic ide support that would allow to build rich 
+  script editing apps and REPLs is outside of the scope of this proposal and will be covered elsewhere.    
+  
+#### Data structures
+  
+- `ScriptSource` determines the way to access script for other components; it consists of:
+  - the script reference pointer: url
+  - an accessor to the script text  
+  Both components are optional but at least one is required for a regular script.  
+  The class implements source position and fragment referencing classes used e.g. in error reporting. 
+- `KotlinType` a wrapper around Kotlin types, used to decouple script definition and compilation/evaluation 
+  environments. It could be constructed either from reflected or from stringified type representation.
+- `ScriptCompilationConfiguration` - a heterogeneous container of parameters defining the script compilation
+- `ScriptEvaluationConfiguration` - a heterogeneous container of parameters defining the script evaluation 
+- `ScriptingHostConfiguration` - a heterogeneous container of host-specific parameters  
+
+### Script definition
+ 
+Script Definition is a way to specify custom script. It is basically consists of a script base class annotated with 
+`KotlinScript` annotation. The arguments of the annotation define the script configuration parameters.  For example: 
+
+```kt
+@KotlinScript(
+    displayName = "My Script",
+    fileExtension = "myscr.kts",
+    compilationConfiguration = MyScriptCompilationConfiguration::class,
+    evaluationConfiguration = MyScriptEvaluationConfiguration::class
+)
+abstract class MyScript(project: Project, val name: String) {
+    fun helper1() { ... } 
+    
+    [@ScriptBody]
+    [suspend] abstract fun <scriptBody>(params...): MyReturnType
+}
+
+object MyScriptCompilationConfiguration : ScriptCompilationConfiguration({
+    defaultImports("java.io.*")
+    providedProperties(prop1 to Int::class, prop2 to String::class)
+})
+
+object MyScriptEvaluationConfiguration : ScriptEvaluationConfiguration({
+    providedProperties(prop1 to 42, prop2 to "foo")
+})
+```
+
+*Where:*
+- any valid method name could be used in place of `<scriptBody>` 
+- `@ScriptBody` annotation marks the method the script body will be compiled into. In the absence of the explicit 
+  annotation, if the configuration requires compilation into a method, the SAM notation will be used, otherwise
+  the script will be generated into the target class constructor.
+- `interface` or `open class` could be used in place of the `abstract class`
+-  *(see also possible compilation configuration properties below)*
+
+The annotations have reasonable defaults, so in the minimal case it is enough to mark the class only with the 
+`@KoltinScript` without parameters. But it is recommended to give a dedicated file name extension for every script 
+type to minimize chances for clashes in case of multiple definitions in one context.
+The file name extension could be declared in the compilation configuration as well, but it is highly recommended
+to define it in the annotation instead, since it will speed up the discovery process significantly.
+
+### Script Compilation
+
+#### Script Compiler
+
+Script compiler implements the following interface:
+```kt
+interface ScriptCompiler {
+
+    /**
+     * Compiles the [script] according to the [scriptCompilationConfiguration]
+     * @param script the interface to the script source code
+     * @param scriptCompilationConfiguration the script compilation configuration properties
+     * @return result wrapper, if successful - with compiled script
+     */
+    suspend operator fun invoke(
+        script: SourceCode,
+        scriptCompilationConfiguration: ScriptCompilationConfiguration
+    ): ResultWithDiagnostics<CompiledScript<*>>
+}
+```
+where:
+```kt
+interface CompiledScript<out ScriptBase : Any> {
+
+    /**
+     * The compilation configuration used for script compilation
+     */
+    val compilationConfiguration: ScriptCompilationConfiguration
+
+    /**
+     * The function that loads compiled script class
+     * @param scriptEvaluationConfiguration the script evaluation configuration properties
+     * @return result wrapper, if successful - with loaded KClass
+     */
+    suspend fun getClass(scriptEvaluationConfiguration: ScriptEvaluationConfiguration?): ResultWithDiagnostics<KClass<*>>
+
+    /**
+     * The name and the type of the script's result field, if any
+     */
+    val resultField: Pair<String, KotlinType>?
+}
+
+```
+The compilers for the supported platforms are supplied by default scripting infrastructure.
+  
+#### Script Dynamic Compilation Configuration
+
+The script compilation could be configured dynamically by specifying configuration refining callbacks in the compilation
+configuration. The callback should be written according to the following signature: 
+```kt
+typealias RefineScriptCompilationConfigurationHandler =
+            (ScriptConfigurationRefinementContext) -> ResultWithDiagnostics<ScriptCompilationConfiguration>
+```
+where:
+```kt
+class ScriptConfigurationRefinementContext(
+    val script: SourceCode,
+    val compilationConfiguration: ScriptCompilationConfiguration,
+    val collectedData: ScriptCollectedData? = null
+)
+```
+and `ScriptCollectedData` is a heterogeneous container of properties with the appropriate data collected during parsing.
+
+See the following section for the parameters that declare such callbacks.
+
+#### Compilation Configuration Properties
+
+The following properties are recognized by the compiler:
+- `baseClass` - target script superclass as well as a source for the script target method signature, constructor
+  parameters and annotations, default - `Any`.
+- `sourceFragments` - script fragments compile - allows to compile script partially
+- `scriptBodyTarget` - defines whether script body will be compiled into resulting class constructor or to a 
+  method body. In the latter case, there should be either single abstract method defined in the script base class, or
+  single appropriate method should be annotated with the `ScriptBody` annotation
+- `implicitReceivers` - a list of script types that is assumed to be implicit receivers for the script body, as
+  if the script is wrapped into `with` expressions, in the order from outer to inner scope, i.e.:  
+  ```kt
+  with(receiver0) {
+      ...
+      with(receiverN) {
+          <script body>
+      }
+  }
+  ```
+- `providedProperties` - a map (name -> type) of external variables visible for the script
+- `defaultImports` - a list of import statements implicitly added to the script
+- `restrictions` - a list of allow/deny rules containing qualified identifier wildcards, which are applied after
+  resolving any identifier used in the script to determine whether a particular identifier should be accessible for 
+  the script. This allows creating hosts with script functionality restrictions
+- `importedScripts` - a list of scripts definitions from which should be available for the compiled script
+- `dependencies` - a list of external libraries or modules available for the script
+- `copyAnnotationsFrom` - an external class those annotations should be copied to the generated target class; if not
+  specified, the annotations are copied from the base class (except for known scripting annotations)
+- `compilerOptions` - a list of additional compiler options that should be passed to compiler on script compilation
+- `resultField` - the name of the generated script class field to assign the script results to, empty means disabled, 
+  default - `$$result`
+- `refineConfigurationBeforeParsing` - a configuration refining callback that should be called before parsing is
+  started
+- `refineConfigurationOnAnnotations` - a list of script file-level annotations and configuration refining callback,
+  if the specified annotations are found in the parsed script, the callback is called to get an updated configuration. 
+- `refineConfigurationOnSections` - a list of top-level "sections" - function calls with single lambda parameter, e.g.  
+  ```kt
+  plugins {
+      ...
+  }
+  ```  
+  and the callback that should be called if specified sections are found in the parsed script
+  
+Additional properties are possible for particular platforms and compiler implementations.
+
+#### Script class
+
+In case of compiling into constructor, the script compiled into the following class
+
+```kt
+@CopiedAnnotation0(...)
+...
+@CopiedAnnotationN(...)
+class Script(
+    baseClassArguments..., 
+    receiver0: ReceiverType0, ..., receiverN: ReceiverTypeN,
+    val providedProperty0: ProvidedPropertyType0, ..., val providedPropertyN: ProvidedPropertyTypeN
+): ScriptBaseClass(baseClassArguments...) {
+    
+    val val1: V1 by initOnce // for all vals/vars defined in the script body
+    
+    fun fn1(...): R1 {} // for all funcs defined in the script body
+    
+    class Cl1(...) {} // for all classes/objects defined in the script body
+    
+    val $$result: ResultType
+    
+    init {
+        with(receiver0) {
+            ...
+            with(receiverN) {
+                <script body>
+                $$result = <last expression>
+            }
+        }
+    }
+}
+```
+
+In case of compiling into a method, the internal script properties are not exposed from the class:
+
+```kt
+@CopiedAnnotation0(...)
+...
+@CopiedAnnotationN(...)
+class Script(
+    baseClassArguments..., 
+    receiver0: ReceiverType0, ..., receiverN: ReceiverTypeN,
+    val providedProperty0: ProvidedPropertyType0, ..., val providedPropertyN: ProvidedPropertyTypeN
+): ScriptBaseClass(baseClassArguments...) {
+    
+    [suspend] fun <scriptBody>(lambdaParams...): ReturnType {
+        with(receiver0) {
+            ...
+            with(receiverN) {
+                <script body>
+            }
+        }
+    }}
+```
+ 
+
+The actual name of the `<scriptBody>` method is defined by the script base class.
+
+The `implicitReceivers` may also contain compiled external scripts objects (from the `importedScripts` property).
+
+*Note: The `with (implicitReceivers)` wrapping is needed in all methods and initializers defined in the class.*
+
+### Script Evaluation
+
+#### Script Evaluator
+
+The script evaluator is an optional service (since the scripting host may choose to instantiate and execute compiled
+scripts manually) for instantiating and running compiled scripts. The default evaluators for supported platforms 
+are provided by the scripting infrastructure. It should implement the following interface:
+```kt
+interface ScriptEvaluator {
+    suspend operator fun invoke(
+        compiledScript: CompiledScript<*>,
+        scriptEvaluationConfiguration: ScriptEvaluationConfiguration?
+    ): ResultWithDiagnostics<EvaluationResult>
+}
+```
+
+#### Evaluation properties
+
+The following properties could be recognized by the evaluator, when passed in the `scriptEvaluationConfiguration` 
+parameter:
+- `implicitReceivers` - a list of actual implicit receivers objects, corresponding to the `implicitReceivers`
+  parameter in the compilation configuration
+- `providedProperties` - a map (name -> value) of the actual external variables visible to the script, corresponding to
+  the `providedProperties` parameter in the compilation configuration
+- `constructorArgs` - a list of constructor parameters corresponding to the script base class constructor, that should 
+  be passed to the script constructor
+- `runArgs` - a list of arguments to the script body method, if the `scriptBodyTarget` is set to the compiling script
+  into the method
+- `scriptsInstancesSharing` - boolean property defining the way of dealing with duplicates among imported scripts - if
+  true - the imported scripts instances are kept in a container and shared among all use sites in the import hierarchy.
+  (the helper `enableScriptsInstancesSharing()` provides another way of turning it on) 
+- `refineConfigurationBeforeEvaluate` - a configuration refining callback that should be called before evaluation is
+  started
+  
+It is possible to define and pass additional properties to a user-defined evaluator.    
+
+#### Scripting host configuration 
+
+These properties are defined by the scripting host and contain general parameters needed for all scripting services.
+In particular, it is assumed that `ScriptCompilationConfigurator` and `ScriptEvaluater` implementations are instantiated
+by passing the environment property bag to the appropriate constructors.  
+The following parameters are defined:
+- `configurationDependencies` - a list of dependencies required for script base class and services (configurator and
+  evaluator), but not necessarily for scripts themselves (see below)
+- `getScriptingClass` - an interface to an implementation-specific "class loader" for types specified in the 
+  configurations
+- `getEvaluationContext` - optional user-supplied function that can provide data to the evaluation configuration 
+  refinement functions 
+  
+### Standard hosts and discovery
+
+For standard JVM compiler, the command line parameter could be used to specify a script definition class name, and 
+then regular compilation classpath will be used for dependencies.
+
+Additionally, the automatic discovery of the templates marked by `@KotlinScript` annotation could be used with 
+libraries that do not have plugins able to provide an extension. This could, for example, be used for test frameworks.  
+In this case, the compiler scans all jars in the classpath for the discovery files - files in the folder 
+`META-INF/kotlin/script/templates/` those names correspond to fully qualified names of the annotated script base 
+classes. *(Note: the files' contents are not used, only the name)*. When it reads the annotations attached to these 
+classes and lazily constructs actual script definitions from them.  
+
+*(Note: the process is optimized in a way that if the file name extension could be extracted from the annotations alone,
+the actual definition is not loaded until we will actually start to compile a script with the appropriate extension. 
+This practically eliminates the overhead of script definitions discovery for projects that are not using scripts.)*
+
+### How to implement scripting support
+     
+To implement scripting support on the JVM one should do the following
+
+- Implement script definition library/module
+   - define custom script compilation configuration class, inherit it from `ScriptCompilationConfiguration` and pass
+     configuration lambda to the constructor of the latter
+   - define custom script evaluation configuration class, inherit it from `ScriptEvaluationConfiguration` and pass
+     configuration lambda to the constructor of the latter
+   - define script base class with the `@KotlinScript` and pass at least file name extension and the configuration 
+     classes to it
+   - optionally add a discovery file named after FQN of the base class to the `META-INF/kotlin/script/templates/` in 
+     the target jar 
+
+If discovery file is added to the resulting jar, and this jar is added to the compilation classapth, it becomes possible 
+to use custom script with the default hosts (e.g. Kotlin command-line compiler) and Kotlin IDEA plugin out of the box.   
+
+*(Note for usage with Gradle: the discovery process is not turned on by default in the Kotlin gradle plugin, to enable
+script definitions discovery in particular dependencies, they should be added to the `kotlinScriptDef` (or 
+`testKotlinScriptDef`, etc.) configuration)*
+
+Optionally the custom host and Idea support could be implemented:
+
+- Implement the scripting host with the following functionality:
+   - collect host configuration properties required for the services
+   - instantiate compiler and evaluator
+   - create basic host e.g. using platform-specific basic implementation   
+   - in case of custom implementation, on each eval:
+     - call compiler
+     - call evaluator
+      
+- Implement IDE support via the appropriate extension
+   - implement a class with `ScriptDefinitionsProvider` that returns appropriate definition class name and classpath
+     needed to load it. 
+   - use `org.jetbrains.kotlin.scriptDefinitionsProvider` extension point to register the provider class in IntelliJ
+   - in the script compilation configuration created as described above, add `ide` section with the following properties:
+     - `acceptedLocations` - the list of possible project locations where the script of this type will be recognized
+       (see. `ScriptAcceptedLocation` enum class for the possible values)
+     - `dependenciesSources` script source dependencies pointing to the jars with source code    
+
+### Implementation status
+
+The experimental implementation of the described scripting infrastructure on the JVM platform is a part of Kotlin 
+starting from the 1.3.0 release. The following API and helper libraries are generally needed for the implementation:
+- `kotlin-scripting-common` - API, interfaces, data structures and properties
+- `kotlin-scripting-jvm` - JVM-specific properties and default implementations
+- `kotlin-scripting-jvm-host` - JVM-specific host helpers
+
+The basic examples could be found in the `libraries/samples/scripting` folder in the Kotlin source code repository.
+
+The implementation is functional for many use cases, but there are many gaps, in particular:
+- the following compilation configuration properties are not supported yet:
+  - `sourceFragments` - scripts are only compiled as a whole for a moment; accordingly - the next point:
+  - `refineConfigurationOnSections` - is not implemented
+  - `scriptBodyTarget` - the generation into method body is not yet supported, so this parameter is ignored
+  - `restrictions` - not implemented yet
+  - `copyAnnotationsFrom` - is not implemented yet, the annotations are copied from the base class
+- some properties are required by the current implementation are not part of this proposal, because they exist only 
+  due to some implementation issues, and could soon disappear or change significantly, for example:
+  - `getScriptingClass` in the environment - is used for kotlin types instantiation; currently the instance of
+    `JvmGetScriptingClass` should be always used
+
+The standard host functionality including discovery is implemented in the command-line compiler, gradle plugin and IDEA
+plugin. But the following limitations are known:
+  - if the script definition module is in the same project as the usage part, the module (and in particular - base 
+    class) should be compiled to class files in order to be recognized by the discovery mechanism
+  - the script compilation in maven project is not supported yet
+  - the mechanisms for managing script definitions and resolving clashes are not implemented
+  - additional configuration is needed to enable script definitions discovery in a gradle build (see note in the 
+    [How to implement scripting support](#how-to-implement-scripting-support) section)
+    
+In general the scripting support is in the experimental stage, so we cannot guarantee stability of the interfaces and 
+implementations.
+
+### Examples
+
+#### kotlin-main-kts
+ 
+The `kotlin-main-kts` artifact contains a script definition and a minimal maven artifacts resolver in a single jar.
+It allows to:
+- create and use the simple utility scripts that may depend on the external libraries;
+- extract the common functionality into “imported” scripts.
+
+It could be used as an example as an advanced script definition or together with standard or custom hosts - as an
+actual scripting tool. It implements JSR-223 host and therefore could be used via the `javax.script` API.
+
+To extend scripts with functionality from 3rd-party libraries and to organize scripts structure, the `kotlin-main-kts`
+implements support of the following file-level annotations:
+- `@DependsOn` allows specifying library dependencies for the script. Either a direct path to the file or jar, or 
+   maven coordinates are accepted as arguments.
+- `@Repository` adds the maven repository for resolving dependencies. If none are specified explicitly, the maven central 
+  repository is used.
+- `@Import` allows importing another script into a given one. All the actions specified in the imported script
+  run before all the actions specified in the given script and all the properties, functions and classes defined
+  in the imported scripts become visible for the given script.
+
+The artifact is distributed along with kotlin command line compiler package and published in Maven
+Central as `org.jetbrains.kotlin:kotlin-main-kts`.
+
+##### Usage
+
+###### Example scripts
+
+common.main.kts:
+```kt
+val greeting = "Hello, World!"
+```
+
+sample.main.kts:
+```kt
+@file:Repository("https://jcenter.bintray.com")
+@file:DependsOn("org.jetbrains.kotlinx:kotlinx-html-jvm:0.6.11")
+@file:Import("common.main.kts")
+
+import kotlinx.html.*
+import kotlinx.html.stream.*
+
+print(createHTML().html {
+    body {
+        h1 { +greeting }
+    }
+})
+```
+
+###### Running from command-line compiler (script definition discovery)
+
+```sh
+kotlinc -cp <path/to/kotlin-main-kts.jar> -script sample.main.kts
+```
+
+###### Simple host: eval function
+
+```kt
+fun evalFile(scriptFile: File): ResultWithDiagnostics<EvaluationResult> {
+
+    val compilationConfiguration = createJvmCompilationConfigurationFromTemplate<MainKtsScript>()
+    val evaluationConfiguration = createJvmEvaluationConfigurationFromTemplate<MainKtsScript>()
+
+    return BasicJvmScriptingHost().eval(scriptFile.toScriptSource(), compilationConfiguration, evaluationConfiguration)
+}
+
+evalFile(File("sample.main.kts")
+```
+
+###### Using JSR-223 (`javax.script`) API
+
+```kt
+val engine = ScriptEngineManager().getEngineByExtension("main.kts")!!
+engine.eval("""
+@file:DependsOn("junit:junit:4.11")
+
+org.junit.Assert.assertTrue(true)
+
+println("Hello, World!")
+""")
+```
+##### Implementation 
+
+The complete source code could be found in the `libraries/tools/kotlin-main-kts` folder in the Kotlin source 
+code repository. Here only partial sources are given to illustrate the main implementation points.
+
+###### Script base class
+
+```kt
+@KotlinScript(
+    fileExtension = "main.kts",
+    compilationConfiguration = MainKtsScriptDefinition::class,
+    evaluationConfiguration = MainKtsEvaluationConfiguration::class
+)
+abstract class MainKtsScript(val args: Array<String>)
+```
+
+###### Script compilation configuration properties
+
+```kt
+object MainKtsScriptDefinition : ScriptCompilationConfiguration(
+    {
+        defaultImports(DependsOn::class, Repository::class, Import::class)
+        jvm {
+            dependenciesFromClassContext( // extract dependencies from the host environment
+                MainKtsScriptDefinition::class, // use this class classloader for dependencies search
+                "kotlin-main-kts", "kotlin-stdlib", "kotlin-reflect" // search these libraries in it and use then as a script compilation classpath
+            )
+        }
+        refineConfiguration {
+            onAnnotations(
+                DependsOn::class, Repository::class, Import::class, // if these annotations are found on script parsing 
+                handler = MainKtsConfigurator() // call this handler to refine configuration parameters
+            )
+        }
+        ide {
+            acceptedLocations(ScriptAcceptedLocation.Everywhere) // these scripts are recognized everywhere in the project structure
+        }
+        jsr223 {
+            importAllBindings(true) // when used as a JSR-223 host, import engine bindings as kotlin properties
+        }
+    })
+```
+
+###### Script evaluation configuration properties
+
+```kt
+object MainKtsEvaluationConfiguration : ScriptEvaluationConfiguration(
+    {
+        scriptsInstancesSharing(true) // if a script is imported multiple times in the import hierarchy, use a single copy
+
+        refineConfigurationBeforeEvaluate( // before evaluation, call this handler to refine configuration properties
+            ::configureProvidedPropertiesFromJsr223Context
+        )
+    }
+)
+```
+
+###### Compilation configuration refinement handler
+
+```kt
+class MainKtsConfigurator : RefineScriptCompilationConfigurationHandler {
+    private val resolver = FilesAndIvyResolver()
+
+    override operator fun invoke(context: ScriptConfigurationRefinementContext): ResultWithDiagnostics<ScriptCompilationConfiguration> =
+        
+        val annotations = context.collectedData?.get(ScriptCollectedData.foundAnnotations)?.takeIf { it.isNotEmpty() }
+            ?: return context.compilationConfiguration.asSuccess()
+
+        // collect imported scripts paths from  Import annotations 
+        val scriptBaseDir = (context.script as? FileBasedScriptSource)?.file?.parentFile
+        val importedSources = annotations.flatMap {
+            (it as? Import)?.paths?.map { sourceName ->
+                FileScriptSource(scriptBaseDir?.resolve(sourceName) ?: File(sourceName))
+            } ?: emptyList()
+        }
+
+        // pass resolving annotations to resolver
+        val resolvedClassPath = try {
+            val scriptContents = object : ScriptContents {
+                override val annotations: Iterable<Annotation> = annotations.filter { it is DependsOn || it is Repository }
+                override val file: File? = null
+                override val text: CharSequence? = null
+            }
+            resolver.resolve(scriptContents, emptyMap(), {}, null).get()?.classpath?.toList()
+            // TODO: add diagnostics
+        } catch (e: Throwable) {
+            return ResultWithDiagnostics.Failure(*diagnostics.toTypedArray(), e.asDiagnostics(path = context.script.locationId))
+        }
+
+        // return updated configuration with resolved dependencies and imported scripts
+        return ScriptCompilationConfiguration(context.compilationConfiguration) {
+            if (resolvedClassPath != null) updateClasspath(resolvedClassPath)
+            if (importedSources.isNotEmpty()) importScripts.append(importedSources)
+        }.asSuccess()
+    }
+}
+```
+
+###### The discovery file (resources)
+  
+`META-INF/kotlin/script/templates/org.jetbrains.kotlin.mainKts.MainKtsScript.classname`
+
diff --git a/proposals/jsr-305-custom-nullability-qualifiers.md b/proposals/KEEP-0079-jsr-305-custom-nullability-qualifiers.md
similarity index 100%
rename from proposals/jsr-305-custom-nullability-qualifiers.md
rename to proposals/KEEP-0079-jsr-305-custom-nullability-qualifiers.md
diff --git a/proposals/local-and-top-level-lateinit-vars.md b/proposals/KEEP-0086-local-and-top-level-lateinit-vars.md
similarity index 100%
rename from proposals/local-and-top-level-lateinit-vars.md
rename to proposals/KEEP-0086-local-and-top-level-lateinit-vars.md
diff --git a/proposals/opt-in.md b/proposals/KEEP-0095-opt-in.md
similarity index 100%
rename from proposals/opt-in.md
rename to proposals/KEEP-0095-opt-in.md
diff --git a/proposals/inline-classes.md b/proposals/KEEP-0104-inline-classes.md
similarity index 100%
rename from proposals/inline-classes.md
rename to proposals/KEEP-0104-inline-classes.md
diff --git a/proposals/functional-types-with-big-arity-on-jvm.md b/proposals/KEEP-0107-functional-types-with-big-arity-on-jvm.md
similarity index 100%
rename from proposals/functional-types-with-big-arity-on-jvm.md
rename to proposals/KEEP-0107-functional-types-with-big-arity-on-jvm.md
diff --git a/proposals/val-in-when-subject.md b/proposals/KEEP-0120-val-in-when-subject.md
similarity index 100%
rename from proposals/val-in-when-subject.md
rename to proposals/KEEP-0120-val-in-when-subject.md
diff --git a/proposals/unsigned-types.md b/proposals/KEEP-0135-unsigned-types.md
similarity index 100%
rename from proposals/unsigned-types.md
rename to proposals/KEEP-0135-unsigned-types.md
diff --git a/proposals/kotlin-contracts.md b/proposals/KEEP-0139-kotlin-contracts.md
similarity index 100%
rename from proposals/kotlin-contracts.md
rename to proposals/KEEP-0139-kotlin-contracts.md
diff --git a/proposals/jvm-static-annotation-in-interface-companion.md b/proposals/KEEP-0150-jvm-static-annotation-in-interface-companion.md
similarity index 100%
rename from proposals/jvm-static-annotation-in-interface-companion.md
rename to proposals/KEEP-0150-jvm-static-annotation-in-interface-companion.md
diff --git a/proposals/jvm-field-annotation-in-interface-companion.md b/proposals/KEEP-0152-jvm-field-annotation-in-interface-companion.md
similarity index 100%
rename from proposals/jvm-field-annotation-in-interface-companion.md
rename to proposals/KEEP-0152-jvm-field-annotation-in-interface-companion.md
diff --git a/proposals/enhancing-main-convention.md b/proposals/KEEP-0158-enhancing-main-convention.md
similarity index 100%
rename from proposals/enhancing-main-convention.md
rename to proposals/KEEP-0158-enhancing-main-convention.md
diff --git a/proposals/named-arguments-in-their-own-position.md b/proposals/KEEP-0193-named-arguments-in-their-own-position.md
similarity index 100%
rename from proposals/named-arguments-in-their-own-position.md
rename to proposals/KEEP-0193-named-arguments-in-their-own-position.md
diff --git a/proposals/sealed-interface-freedom.md b/proposals/KEEP-0226-sealed-interface-freedom.md
similarity index 100%
rename from proposals/sealed-interface-freedom.md
rename to proposals/KEEP-0226-sealed-interface-freedom.md
diff --git a/proposals/jvm-records.md b/proposals/KEEP-0233-jvm-records.md
similarity index 100%
rename from proposals/jvm-records.md
rename to proposals/KEEP-0233-jvm-records.md
diff --git a/proposals/repeatable-annotations.md b/proposals/KEEP-0257-repeatable-annotations.md
similarity index 100%
rename from proposals/repeatable-annotations.md
rename to proposals/KEEP-0257-repeatable-annotations.md
diff --git a/proposals/KEEP-0259-context-receivers.md b/proposals/KEEP-0259-context-receivers.md
new file mode 100644
index 000000000..b71f7180d
--- /dev/null
+++ b/proposals/KEEP-0259-context-receivers.md
@@ -0,0 +1,1371 @@
+# Context receivers
+
+* **Type**: Design proposal
+* **Authors**: Roman Elizarov, Anastasia Shadrina
+* **Contributors**: Denis Zharkov, Marat Akhin, Mikhail Belyaev, Ilya Gorbunov, Ilmir Usmanov, Simon Ogorodnik,
+  Dmitriy Novozhilov, Mikhail Glukhikh
+* **Status**: Experimental in 1.6.20-M1
+* **Discussion**: [KEEP-259](https://github.com/Kotlin/KEEP/issues/259)
+* **Prototype**: Implemented
+
+## Abstract
+
+This is a design proposal for support of context-dependent declarations in Kotlin. 
+It covers a large variety of use cases and was previously known and requested under the name of
+"multiple receivers", see [KT-10468](https://youtrack.jetbrains.com/issue/KT-10468).
+
+We would appreciate hearing your feedback on this proposal in the [KEEP-259](https://github.com/Kotlin/KEEP/issues/259).
+
+## Table of Contents
+
+<!--- TOC -->
+
+* [Introduction](#introduction)
+  * [Context receivers and contextual declarations](#context-receivers-and-contextual-declarations)
+  * [Goals](#goals)
+* [Detailed design](#detailed-design)
+  * [Contextual functions and property accessors](#contextual-functions-and-property-accessors)
+  * [Functional types](#functional-types)
+  * [Referencing specific receiver](#referencing-specific-receiver)
+  * [Resolution algorithm](#resolution-algorithm)
+  * [Backwards compatibility](#backwards-compatibility)
+  * [JVM ABI and Java compatibility](#jvm-abi-and-java-compatibility)
+* [Use cases](#use-cases)
+* [Contexts and coding style](#contexts-and-coding-style)
+  * [Overloading by the presence of context](#overloading-by-the-presence-of-context)
+  * [Performing an action on an object](#performing-an-action-on-an-object)
+  * [Providing additional parameters to an action](#providing-additional-parameters-to-an-action)
+  * [Providing additional context for an action](#providing-additional-context-for-an-action)
+  * [Kotlin builders](#kotlin-builders)
+  * [Other Kotlin DSLs](#other-kotlin-dsls)
+  * [Designing context types](#designing-context-types)
+* [Similar features in other languages](#similar-features-in-other-languages)
+  * [Scala given instances and using clauses](#scala-given-instances-and-using-clauses)
+  * [Algebraic effects and coeffects](#algebraic-effects-and-coeffects)
+* [Alternative approaches and design tradeoffs](#alternative-approaches-and-design-tradeoffs)
+  * [Alternative syntax options](#alternative-syntax-options)
+  * [Alternative keywords](#alternative-keywords)
+  * [Parentheses vs angle brackets](#parentheses-vs-angle-brackets)
+  * [Context keyword ambiguities](#context-keyword-ambiguities)
+  * [Named context receivers](#named-context-receivers)
+  * [Multiple receivers with decorators](#multiple-receivers-with-decorators)
+* [Future work](#future-work)
+  * [Reflection design](#reflection-design)
+  * [Contextual delegated properties](#contextual-delegated-properties)
+  * [Local contextual functions and properties](#local-contextual-functions-and-properties)
+  * [Callable references to contextual functions](#callable-references-to-contextual-functions)
+  * [Removing context receiver from the scope with DslMarker](#removing-context-receiver-from-the-scope-with-dslmarker)
+  * [Scope properties](#scope-properties)
+  * [Contextual classes and contextual constructors](#contextual-classes-and-contextual-constructors)
+  * [Future decorators](#future-decorators)
+  * [Unified context properties](#unified-context-properties)
+* [Open issues and concerns](#open-issues-and-concerns)
+  * [Context receivers abuse and scope pollution](#context-receivers-abuse-and-scope-pollution)
+  * [Methods from Any in top-level functions](#methods-from-any-in-top-level-functions)
+* [Prototype](#prototype)
+
+<!--- END -->
+
+## Introduction
+
+Consider an interface `Scope` that represents some context and another interface `Entity` that we want to define an
+action on, so that this action is available only in a context that provides an instance of a `Scope`, without having to
+explicitly pass the `Scope` around.
+
+In Kotlin, you can define such a context-restricted declaration using a
+[member extension function](https://kotlinlang.org/docs/extensions.html#declaring-extensions-as-members).
+A member extension has two receivers: a dispatch receiver from the class and an extension receiver from the method's extension.
+
+```kotlin
+interface Entity
+
+interface Scope { // Scope is a dispatch receiver
+    fun Entity.doAction() { // Entity is an extension receiver for doAction
+        ...
+    }
+}
+```
+
+> A real-life example of a `Scope` could be [`CoroutineScope`](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/),
+> from the [`kotlinx.coroutines`](https://github.com/Kotlin/kotlinx.coroutines) library. You must provide a `CoroutineScope`
+> to be able to launch new coroutines as a part of an action. A real-life example of an `Entity` could be a
+> [`Flow`](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html)
+> with an operation to launch a coroutine that collects a flow.
+
+When calling a `doAction` member extension function, its dispatch receiver `Scope` must be present in the caller's scope.
+There is no dedicated syntax to explicitly specify a dispatch receiver for such a call. On the other hand, the extension
+receiver `Entity` can and is usually specified explicitly using `entity.doAction()` qualified call syntax.
+To specify a `Scope` dispatch receiver we can use a **scope function**, like
+[with](https://kotlinlang.org/docs/scope-functions.html#with), [run](https://kotlinlang.org/docs/scope-functions.html#run),
+or [apply](https://kotlinlang.org/docs/scope-functions.html#apply), to bring it into scope:
+
+```kotlin
+with(scope) {
+    entity.doAction()
+}
+```
+
+We say that an extension receiver defines the **object of an action**, while a dispatch receiver effectively serves as
+an implicit parameter that must be present in the caller's scope but cannot be specified explicitly. Thus, a member
+extension function can be called a context-dependent function, and a dispatch receiver represents the **context of an action**.
+
+The context-oriented approach has many applications in the design of idiomatic Kotlin APIs (for example, see
+["An introduction to context-oriented programming in Kotlin" by Alexander Nozik](https://proandroiddev.com/an-introduction-context-oriented-programming-in-kotlin-2e79d316b0a2))
+and is a building block of a more generic [code coloring concept](https://github.com/Kotlin/KEEP/blob/master/notes/code-coloring.md).
+However, a member extension is now the only way to define a context-dependent declaration, and this form has
+multiple limitations that restrict its practical usefulness.
+
+The key one is that a **member extension cannot be declared on a third-party class**. It limits the ability to decouple,
+modularize and structure APIs in larger applications. The only way to introduce a context-dependent `Entity.doAction`
+extension is to write it as a member of a `Scope`, which is not always appropriate from a modularity standpoint.
+
+> For example, in the `kotlinx.coroutines` library, it would be inappropriate to declare a `Flow.launchFlow()` extension as
+> a member of `CoroutineScope`, because `CoroutineScope` is a more general concept and its declaration shall not depend
+> on a more specific concept like `Flow`.
+
+Another limitation is that **a member extension is always the extension**. An extension function in Kotlin has an option
+of being called with qualified syntax as in `entity.doAction()`. This is a stylistically appropriate syntax when an
+action is performed on an entity. However, some functions don't operate on a specific entity and should not be declared
+as such. There is no way to declare a top-level function to be called as `doAction()` that would require the presence of
+a specific context in scope.
+
+> Use cases for that come a lot. For example, it would be helpful to be able to define a `TransactionScope` and have
+> syntax to declare transactional functions that have a requirement of being called only in a `TransactionScope`, but
+> forbid an explicit `transaction.doSomething()` call, since they do not work **on** a transaction, but **in the context of**
+> a transaction. 
+
+The final limitation of providing context with a member extension is that **only one receiver can represent a context**.
+It limits composability of various abstractions, as we cannot declare a function that must be called only within two
+or more scopes present at the same time.
+
+> For example, there might be a need to define a function that requires a `CoroutineScope` to be able to launch a
+> coroutine and requires a `TransactionScope` at the same time.
+
+### Context receivers and contextual declarations
+
+This proposal introduces the syntax for defining context-dependent declarations with special **context receivers**.
+This feature overcomes highlighted limitations and covers a variety of use cases.
+
+The context here is not directly related to the action but is used by the action. It can provide additional operations,
+configuration, or execution context. A good example of context would be `Comparator`, `CoroutineScope`, some kind of
+`Transaction` or `LoggingContext` (see [Use cases](#use-cases) for details).
+A simple **contextual function** is declared like this:
+
+```kotlin
+context(Scope)
+fun Entity.doAction()
+```
+
+A top-level contextual function can also be declared:
+
+```kotlin
+context(Scope)
+fun doAction()
+```
+
+Its key difference from the `Scope.doAction` extension is that it cannot be called with a qualified `scope.doAction()`
+syntax, and it has no `this` reference inside its body, since it has no object on which it performs its action.
+Moreover, there can be multiple context receivers. See [Detailed design](#detailed-design) section.
+
+### Goals
+
+* Remove all limitations of member extensions for writing contextual abstractions
+    * Support top-level (non-member) contextual functions and properties
+    * Support adding contextual function and properties to 3rd party context classes
+    * Support multiple contexts
+* Make blocks of code with multiple receivers representable in Kotlin's type system
+* Separate the concepts of extension and dispatch receivers from the concept of context receivers
+    * Context receivers should not change the meaning of unqualified `this` expression
+    * Multiple contexts should not be ordered during resolution, resolution ambiguities shall be reported
+* Design a scalable resolution algorithm with respect to the number of receivers
+    * Call resolution should not be exponential in the number of context receivers
+
+## Detailed design
+
+A context requirement for a declaration is expressed by a new modifier with the `context` keyword 
+followed by the list of context receiver types in parenthesis. The list can contain one or more comma-separated types
+(a trailing comma is supported, too, for use in multi-line declarations).
+
+```kotlin
+context(A, B, C)
+```
+
+> As a matter of coding style, context receivers are defined after annotations and before other modifiers
+> on a separate line.
+
+The following types of declarations can be contextual:
+
+* Functions (top-level, member, extensions functions are currently supported)
+* Property getters and setters (of all these kinds, too)
+
+The types listed as context receivers of a declaration are not allowed to repeat, and no pair
+of them is allowed to have a subtype relation between them.
+
+> This constraint comes from the greedy nature of the [Resolution algorithm](#resolution-algorithm) and absence
+> of any way to explicitly pass context arguments into a call. 
+
+> In the current [prototype](#prototype) implemented in 1.6.20-M1, you won't receive an error on a declaration-site 
+> if there are repeated context receivers. The compiler will report an error only on a call-site.
+
+### Contextual functions and property accessors
+
+For functions and property accessors, context receivers are additional **context parameters** of those
+declarations. They differ from regular parameters in that they are anonymous and are passed
+implicitly just like receivers. 
+In the body of the corresponding function or property accessor they bring the corresponding arguments 
+into the body scope as implicit receivers for further calls.
+
+Take a look at the following example.
+
+```kotlin
+context(Comparator<T>)
+infix operator fun <T> T.compareTo(other: T) = compare(this, other)
+
+context(Comparator<T>)
+val <T> Pair<T, T>.max get() = if (first > second) first else second
+```
+
+* In the first declaration, `compare` is resolved to `Comparator.compare`, because `Comparator<T>` is a context receiver.
+* In the second declaration, the expression `first > second` calls the previously defined operator function `compareTo`, because
+  `Comparator<T>` is a context receiver and can be implicitly passed to `compareTo` as its context parameter.
+
+If a function or a property accessor is a member of some class or interface and has context receivers, then its
+overrides must have context receivers of the same types.
+
+```kotlin
+interface Canvas
+
+interface Shape {
+    context(Canvas)
+    fun draw()
+}
+
+class Circle : Shape {
+    context(Canvas)
+    override fun draw() {
+      ...
+    }
+}
+```
+
+> No widening of context types is allowed on override, context receivers are very similar to function 
+> parameters in this respect.
+
+### Functional types
+
+The functional type of a contextual function can be denoted with the same modifier `context(...)`, which
+should be present at the beginning of the functional type signature.
+
+```kotlin
+typealias ClickHandler = context(Button) (ClickEvent) -> Unit
+```
+
+In the type system, the functional type with context receivers (just as the functional type with an ordinary receiver)
+is equivalent to the similar type having all context receiver types as the types of additional arguments. The resulting
+signature of the functional type replicates the textual order in which every argument appears. It means:
+
+* The type `context(C1, C2) R.(P1, P2) -> T` will actually turn into an instance of the type constructor
+  `Function5<C1, C2, R, P1, P2, T>`.
+
+* Such assignments are valid:
+  ```kotlin
+  fun main() {
+    var g: context(Context) Receiver.(Param) -> Unit
+    g = ::foo         // OK
+    g = ::bar         // OK
+    g = Receiver::baz // OK
+  }
+  
+  fun foo(context: Context, receiver: Receiver, p: Param) {}
+
+  context(Context)
+  fun bar(receiver: Receiver, p: Param) {}
+
+  context(Context)
+  fun Receiver.baz(p: Param) {}
+  ```
+  
+Conceptually, context receivers of a declaration have no order. However, a signature of a contextual functional type 
+replicates the textual order they are declared in. We consider the future introduction of automatic conversion between 
+two similar functional types that differ only in the order of context receivers (for example, `context(A, B) () -> Unit`
+and `context(B, A) () -> Unit`). In 1.6.20, it won't be supported. 
+
+> In the current [prototype](#prototype), you can invoke a contextual functional type only by passing all receivers 
+> (including an extension receiver) as arguments explicitly. For example:
+> ```kotlin
+> context(C)
+> fun R.f(g: context(C) R.(Param) -> Unit, p: Param) {
+>     g(this@C, this@R, p)
+> }
+> ```
+> 
+
+### Referencing specific receiver
+
+Context receivers can never be referenced using a plain `this` expression and never change the meaning of `this`.
+However, this proposal introduces another option to reference a receiver of any type, including context one, via the
+[labeled `this` expression](https://kotlinlang.org/docs/reference/grammar.html#THIS_AT).
+For every receiver in the scope, the compiler generates the label from the name of its type with the following rules:
+
+* If the receiver type is parenthesized, parentheses are omitted
+* If the receiver type is nullable, the question mark is omitted
+* If the receiver type has type arguments or type parameters, they are omitted
+* If the receiver type is a type alias or class, the label is generated from its short name without type parameters
+* If the receiver type is functional, no label is generated
+
+```kotlin
+context(Logger, Storage<User>)
+fun userInfo(name: String): Storage<User>.Info {
+    this@Logger.info("Retrieving info about $name")
+    return this@Storage.info(name)
+}
+```
+
+> Note that referencing a receiver via a labeled `this` expression is now supported only by the compiler.
+> Full IDE plugin support is planned to be implemented soon.
+
+If multiple receivers have the same generated label, none of them can be referenced with the qualified `this`.
+In cases where the label cannot be generated or referenced, a workaround is to use a type alias.
+
+```kotlin
+typealias IterableClass<C, T> = (C) -> Iterator<T>
+
+context(IterableClass<C, T>)
+operator fun <C, T> C.iterator(): Iterator<T> = this@IterableClass.invoke(this)
+```
+
+Using labeled `this` may come in handy even without context receivers. If multiple receivers in a nested scope can be 
+addressed via plain `this`, the use of it becomes ambiguous and decreases readability. Using a bare type name rather 
+than a function name for a label looks more natural since the object type describes the object better than the scope it 
+belongs to ([KT-21387](https://youtrack.jetbrains.com/issue/KT-21387)).
+
+```kotlin
+fun List<Int>.decimateEveryEvenThird() = buildSequence {
+    var counter = 1
+    for (e in this@List) {
+        if (e % 2 == 0 && counter % 3 == 0) {
+            yield(e)
+        }
+        counter += 1
+    }
+}
+```
+
+### Resolution algorithm
+
+The current Kotlin call resolution algorithm is documented in the [Kotlin specification](https://kotlinlang.org/spec/overload-resolution.html#overload-resolution). Contextual receivers introduce a number of changes.
+
+For the purpose of call resolution, context receivers in the scope are considered with all the other implicit receivers in scope. However, they don't have a total hierarchy like other implicit receivers that come from nested syntactic structures.
+Instead, they form non-overlapping groups according to the affected scope. 
+There is no actual order inside groups, but groups themselves are sorted in the scope order: 
+from the innermost to the outermost.
+
+When selecting a candidate of the call, the context parameters of the candidates are initially ignored. Only extension
+and dispatch receivers participate in the algorithm of candidate selection.
+
+> This and other features explained below ensure that the algorithm is not exponential 
+> with respect to the number of context receivers in the function declaration.
+
+When looking for candidates, the whole group of context receivers is processed.
+Multiple applicable candidates in the same group result in ambiguity. If a suitable candidate is found in some group, name resolution ends. In the initially proposed
+implementation, we only consider (non-local) contextual function and properties, so there could be only one group of
+contexts in a scope.
+
+```kotlin
+class A {
+    context(B1, B2)
+    fun C.f() { 
+       // A group: [B1, B2] 
+       with (d) { // Add receiver to the scope
+           // Resolution order: d -> C -> A -> [B1, B2] -> imports
+       }  
+    }
+}
+```
+
+When the candidate target of a call has context requirements itself, those requirements are resolved greedily.
+For each context parameter of a candidate, the first implicit receiver with a suitable type is considered to be used as 
+a context argument of the corresponding call. If a type of a declared context parameter of a candidate uses a generic
+type whose value is not determined yet, then the corresponding type constraints are added to the 
+_constraint system_ of this candidate call. If solving this system fails, then the candidate is considered to be inapplicable, 
+without trying to substitute different implicit receivers available in the context.
+
+Candidates with context requirements are considered to be _more specific_ for the purpose of call resolution
+than the same candidates without context requirements.
+
+> Currently, we don't define a specificity relation between candidates having different sets of context parameters
+> for the lack of compelling use cases for doing so. It can be introduced later in a backwards-compatible way
+> if needed.
+
+Further details of this algorithm will be presented as a part of the Kotlin specification revision.
+
+### Backwards compatibility
+
+The `context(Ctx)` syntax for a function modifier may change the meaning of a previously valid code if we add support
+for local contextual functions in the future. For example:
+
+```kotlin
+open class Ctx {
+    companion object : Ctx
+}
+
+fun context(ctx: Ctx) { ... }
+
+fun foo() {
+    context(Ctx) // Invokes function "context" with "Ctx" companion object
+    fun bar() { ... } // Local function bar
+}
+```
+
+It is not a concern in the initially proposed implementation, which does not support local contextual functions and
+properties. To support them in the future we'll have to deprecate such ambiguous uses of user-defined `context` functions.
+However, we could not find any real Kotlin code that will be affected, so a potential impact of such deprecation is
+extremely low.
+
+> We don't need to turn `context` into a hard keyword and forbid using it as a function or property name. It will be
+> a soft-keyword and remain allowed for use as an identifier.
+
+### JVM ABI and Java compatibility
+
+In the JVM, the contextual function is just an ordinary method with an expanded parameter list. Parameters have textual
+order according to the functional type signature: context receivers go right after the dispatch receiver (if present)
+and before the extension receiver (if present). For the contextual property, the same applies to its getter and setter.
+
+Assume the following top-level contextual function signature:
+
+```kotlin
+context(C1, C2)
+fun R.f(p1: P1, p2: P2)
+```
+
+After compilation, it will turn into the following JVM method signature:
+
+```java
+public static final void f(C1 c1, C2 c2, R r, P1 p1, P2 p2)
+```
+
+And you can call it from Java as a regular static member:
+
+```java
+public class TestF {
+    public static void test(C1 c1, C2 c2, R r, P1 p1, P2 p2) {
+        MainKt.f(c1, c2, r, p1, p2);
+    }
+}
+```
+
+## Use cases
+
+Context receivers can be useful in many domains and applications. 
+An assortment of use cases is presented below.
+
+> Most of the use cases are from the [original discussion](https://youtrack.jetbrains.com/issue/KT-10468).
+
+* Injecting loggers and other contextual information into functions and classes
+  ```kotlin
+  interface LoggingContext {
+      val log: Logger // this context provides reference to logger  
+  }
+  
+  context(LoggingContext)
+  fun performSomeBusinessOperation(withParams: Params) {
+      log.info("Operation has started")
+  }
+  ```
+  
+* Calculating density-independent pixels in Android
+  ```kotlin
+  context(View)
+  val Float.dp get() = this * resources.displayMetrics.density
+  
+  context(View)
+  val Int.dp get() = this.toFloat().dp
+  ```
+  
+* Creating JSONs with [JSONObject](https://www.javadoc.io/doc/com.google.code.gson/gson/2.8.5/com/google/gson/JsonObject.html)
+  and custom DSL
+  
+  ```kotlin
+  fun json(build: JSONObject.() -> Unit) = JSONObject().apply { build() }
+
+  context(JSONObject)
+  infix fun String.by(build: JSONObject.() -> Unit) = put(this, JSONObject().build())
+
+  context(JSONObject)
+  infix fun String.by(value: Any) = put(this, value)
+
+  fun main() {
+      val json = json {
+          "name" by "Kotlin"
+          "age" by 10
+          "creator" by {
+              "name" by "JetBrains"
+              "age" by "21"
+          }
+      }
+  }
+  ```
+  
+* Working with mathematical abstractions
+  ```kotlin
+  context(Monoid<T>)
+  fun <T> List<T>.sum(): T = fold(unit) { acc, e -> acc.combine(e) }
+  ```
+  
+* Using structured concurrency
+  ```kotlin
+  context(CoroutineScope)
+  fun <T> Flow<T>.launchFlow() {
+      launch { collect() }  
+  }
+  ```
+  
+* Declaring transactional functions
+  ```kotlin
+  context(Transaction)
+  fun updateUserSession() {
+      val session = loadSession()
+      session.lastAccess = now()
+      storeSession(session)
+  }
+  ```
+  
+* Conveniently scoping automatically closeable resources (flexible “try-with-resources”)
+  ```kotlin
+  interface AutoCloseScope {
+      fun defer(closeBlock: () -> Unit)
+  }
+
+  context(AutoCloseScope)
+  fun File.open(): InputStream
+
+  fun withAutoClose(block: context(AutoCloseScope) () -> Unit) {
+      val scope = AutoCloseScopeImpl() // Not shown here
+      try {
+          with(scope) { block() }
+      } finally {
+          scope.close()
+      }   
+  }
+
+  // usage
+  withAutoClose {
+      val input = File("input.txt").open()
+      val config = File("config.txt").open()
+      // Work
+      // All files are closed at the end
+  }
+  ```
+
+## Contexts and coding style
+
+Addition of context receivers to the language creates a new dimension in the coding style considerations — in what cases
+it is appropriate to use context receivers and what kind of classes or interfaces are best suited for that role.
+
+From the coding style and naming perspective, members and extensions of context receivers shall be treated very much
+like top-level declarations. In fact, context receivers can be viewed as a context-dependent importing mechanism with
+the caveat that they effectively import a number of declarations with a wildcard import `*`.
+Compare the following declaration of a `doSomething` function with an import:
+
+```kotlin
+import mypackage.*
+
+fun doSomething() { ... }
+```
+
+And a similar declaration using a context receiver:
+
+```kotlin
+context(MyContext)
+fun doSomething() { ... }
+```
+
+In both cases, the code in the `doSomething` body can refer to the declarations inside either `mypackage` or
+inside `MyContext` using their short unqualified names. The names of declarations in the corresponding context,
+just like the names of the top-level declarations, must be unambiguous to the maximal extent, to ensure readability
+of the resulting code.
+
+In practice, it means that very few existing classes or interfaces in a typical Kotlin codebase would fit a role of
+a context receiver. A typical class is designed with `instance.member` call-site usage in mind, as in `user.name`.  
+On the other hand, top-level declarations are designed to be used by their short name without a qualifier.
+
+### Overloading by the presence of context
+
+It is tempting to give functions in contextual receivers the same names as the names of existing top-level functions, 
+so that their behavior changes in the specific context. For example, the Kotlin standard library has a top-level
+[`println`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.io/println.html) function, so you can write:
+
+```kotlin
+fun hello() {
+    println("Hello")
+}
+```
+
+The `println` function is also declared in the [`java.io.PrintWriter`](https://docs.oracle.com/javase/8/docs/api/java/io/PrintWriter.html) class.
+By adding `context(PrintWriter)` to the `hello` function declaration, you can change it to 
+start printing to `PrintWriter` without otherwise changing a single line of code inside it:
+
+```kotlin
+context(PrintWriter)
+fun hello() {
+    println("Hello")
+}
+```
+
+It might be a neat trick for a small application, but it is a very error-prone practice for a larger codebase. It becomes 
+all too easy to call other functions from `hello` which also call `println` themselves and to forget about `context(PrintWriter)`:
+
+```kotlin
+context(PrintWriter)
+fun hello() {
+    println("Hello")
+    world()
+}
+
+// forgot the context
+fun world() {
+    println("World")
+}
+```
+
+The above code still compiles (because there is a top-level `println` function) but it does not do what 
+you likely intended it to do. **Don't do this**. 
+
+A rule of thumb is that the names of functions available on the context receivers should be distinct from the 
+functions available at the top-level in your application.
+
+> For the same reason, it is a bad idea to add language support for any kind of default values for contextual receivers,
+as it will make a similar mistake (of forgetting to pass the context along) undetectable during compilation.
+
+### Performing an action on an object
+
+When writing code that performs an action on an object it is customary in Kotlin to refer to their members
+and extensions by their short name. It is possible to be explicit using `this.`, but it is not recommended in Kotlin
+to write in cases when there are no ambiguities. For example, this is how members and extensions are implemented in
+a typical class:
+
+```kotlin
+class User(
+    val name: String,
+    var updateTime: Instant,
+) {
+    fun updateNow() {
+        updateTime = now() // Notice that we don't write this.updateTime here
+    }
+}
+```
+
+To ensure readability it is important to write code so that there is always a single object on which the action
+is performed upon and pass all additional information in explicitly named parameters. This practice is enforced by the
+Kotlin syntax that allows the definition of only a single extension receiver in a function declaration. So, when writing
+extensions that perform an action on an object **don't do this**:
+
+```kotlin
+context(User)
+fun updateNow() {
+    updateTime = now() // BAD STYLE: Don't use a context receiver here
+}
+```
+
+**Do this**:
+
+```kotlin
+fun User.updateNow() {
+    updateTime = now() // GOOD STYLE: Action is performed on an extension receiver
+}
+```
+
+Even though both declarations are similar in many aspects, and their bodies look similar, the declaration of
+`fun User.updateNow()` is explicit about the intent to perform an action on the `User` object.
+
+### Providing additional parameters to an action
+
+When an action takes additional parameters that specify what kind of operation shall happen, the normal Kotlin parameters
+shall be used, for example, **do this**:
+
+```kotlin
+fun User.recordLastLogin(address: InetAddress) {
+    lastLoginAddress = address // GOOD STYLE: passing parameter explicitly
+}
+```
+
+Don't use context parameters as a way to implicitly pass additional parameters, even though it is technically possible.
+**Don't do this**:
+
+```kotlin
+context(InetAddress)
+fun User.recordLastLogin() {
+    lastLoginAddress = this@InetAddress // BAD STYLE: Don't use context as an implict parameter
+}
+```
+
+### Providing additional context for an action
+
+Context receivers shall be used to provide additional, ubiquitous context for actions. As a litmus test, ask yourself
+if that information might have been provided via a global top-level scope in a smaller application
+with a simpler architecture. If the answer is yes, then it might be a good idea to provide it via a context receiver.
+For example, it is a good idea to inject the source of the current time into various time-dependent functions,
+so you might declare a context that provides current time and pass it to time-dependent functions as a context parameter:
+
+```kotlin
+interface TimeSource {
+    fun now(): Instant
+}
+
+context(TimeSource)
+fun updateNow() {
+    updateTime = now() // GOOD STYLE: Use time source from the context
+} 
+```
+
+### Kotlin builders
+
+The following builder pattern is often used in idiomatic Kotlin code:
+
+```kotlin
+fun someObject(builder: SomeObjectBuilder.() -> Unit) =
+    SomeObjectBuilder().run {
+        builder()
+        build()
+    }
+
+// Later in code
+someObject {
+    property = value
+    ...
+}
+```
+
+This builder pattern uses a functional type with an extension receiver `SomeObjectBuilder.() -> Unit` for good and shall
+continue doing so. Conceptually, the code inside `someObject { ... }` block performs an action upon the `SomeObjectBuilder` instance
+and using an extension receiver for this is in style. We do not recommend using context receivers for such simple builders.
+
+However, context receivers make it possible to define _contextual operators_ &mdash; operators that are available 
+only in the context of the corresponding builder, as shown in "Creating JSONs" example in the [Use cases](#use-cases) section.
+This is a legitimate use-case of context receivers for builders. 
+
+### Other Kotlin DSLs
+
+Other kinds of Kotlin DSLs, beyond builders, shall reconsider their use of extension receivers. Sometimes a Kotlin DSL
+is designed to inject a context into a block. For example, in current Kotlin code bases you might find declarations like
+
+```kotlin
+fun withVirtualTimeSource(block: TimeSource.() -> Unit) { ... }
+
+// Later in code
+withVirtualTimeSource {
+    val time = now() // provides virtual time in this block
+}
+```
+
+This is a good Kotlin style now, and there is no need to reconsider it for stable APIs. However, new Kotlin code shall
+be designed with context receivers in mind:
+
+```kotlin
+// GOOD STYLE: Better for newly designed code
+fun withVirtualTimeSource(block: context(TimeSource) () -> Unit) { ... }
+
+// Later in code
+withVirtualTimeSource {
+    val time = now() // Provides virtual time in this block
+}
+```
+
+This is not only stylistically better, as it clearly shows an intent to provide contextual information. 
+It is also better in a larger codebase, because the contextual lambda in `withVirtualTimeSource { ... }` does not
+change the meaning of `this` reference, for example:
+
+```kotlin
+class Subject { 
+    fun doSomething() {
+        withVirtualTimeSource {
+            val subject = this // `this` still refers to Subject instance
+        }
+    }
+}
+```
+
+### Designing context types
+
+You'd usually need to design new types from scratch to use them as context parameters due to the unique requirement on
+the naming of their members and extensions. They must be designed with context in mind. Use the same naming guidelines
+as if you are designing top-level declarations. A typical business-object would be usually inappropriate as a context receiver.
+
+Prefer interfaces to classes for context receivers. This would help you later on as your application grows — instead
+of carrying a number of different contexts in your top-level functions as in:
+
+```kotlin
+context(TimeSource, TransactionContext, LoggingContext, ...) // BAD: Too many separate contexts
+fun doSomeTopLevelOperation() { ... }
+```
+
+You'll have an option of combining multiple contexts into a single meaningfully named interface:
+
+```kotlin
+interface TopLevelContext : TimeSource, TransactionContext, LoggingContext, ...
+
+context(TopLevelContext) // GOOD: A combined context
+fun doSomeTopLevelOperation() { ... }
+```
+
+## Similar features in other languages
+
+Contextual abstractions exist in other languages.
+
+### Scala given instances and using clauses
+
+Scala 2 introduced the first implementation of contextual abstractions with "impicits": implicit objects, definitions,
+classes, and parameters. In Scala 3, "implicits" were redesigned and turned into given instances, using clauses and
+extension methods. Using clauses have a lot in common with context receivers.
+
+`using` always works together with some `given`. Given instance defines a value of a certain type, which the compiler can
+further use to generate an implicit argument for calls with a context parameter of this type.
+Meanwhile, a context parameter is defined with a `using` clause.
+
+```scala
+// Can be called only in the scope with the given of Ordering[Person] type
+def printPersons(s: Seq[Person])(using ord: Ordering[Person]) = ...
+```
+
+Context parameters are quite close to the context receivers we're describing in this proposal — they also consume a context
+from a caller scope. So the example above can be easily translated into Kotlin, preserving its semantics:
+
+```kotlin
+// Can be called only in the scope with the context receiver of Comparator<Person> type
+context(Comparator<Person>)
+fun printPersons(s: Sequence<Person>) = TODO()
+```
+
+### Algebraic effects and coeffects
+
+Algebraic effects is a mechanism that is being implemented in some research languages such as
+[Eff](https://www.eff-lang.org/) (with untyped effects) and [Koka](https://github.com/koka-lang/koka) (with typed effects)
+to model various effects that a function can have on its environment. For pure functional languages, they provide a
+unified abstraction for things like reading and writing state, throwing exceptions, doing input and output, etc.
+In essence, effects are similar to exceptions, but, unlike exceptions, which always abort the function's execution
+when thrown, effects can choose to continue execution. This is what makes it possible, for example, to use effects
+to model a computation that emits a string. For example, take a look at this example from Koka:
+
+```koka
+effect emit { // Somewhat similar to 'interface' declaration
+    fun emit(msg: string): () // '()' denotes 'Unit' in Koka
+}
+
+fun hello(): emit () { // Function has an effect of 'emit', returns `()`
+    emit("hello world!")
+}
+```
+
+The `hello` function must be called with the handler for the `emit` effect. For example, one can
+[print](https://koka-lang.github.io/koka/doc/std_core.html#println) emitted messages to the console:
+
+```koka
+fun helloToConsole() {
+    with handler { fun emit(msg) { println(msg) } }
+    hello()
+}
+```
+
+In languages with effects, the effects are modeled in a type system together with the return type. For example,
+the `hello` function in Koka has a type of `() -> emit ()` as it has no parameters, has an `emit` effect, and returns unit.
+Here the similarity of effects to checked (typed) exceptions is also apparent as checked exceptions represent a
+limited form of typed (checked) effects.
+
+Coeffects constitute a dual approach to modelling the same behavior as with effects. Instead of looking at effects
+that a function has, we can look at the context in which the function can be run (see
+[Thomas Petricek's work for details](http://tomasp.net/coeffects/)). Kotlin context receivers are a limited form of a typed
+(checked) coffect system. We can rewrite the declaration of the `hello` function with an `emit` effect to Kotlin as a
+function that requires an `Emit` context:
+
+```kotlin
+fun interface Emit {
+    fun emit(msg: String)
+}
+
+context(Emit)
+fun hello() {
+    emit("hello world!")
+}
+```
+
+Similarly to how effectful code can be only run with the handler for the corresponding effect, the contextual functions
+can only be run in the corresponding context:
+
+```kotlin
+fun helloToConsole() {
+    with(Emit { msg -> println(msg) }) {
+        hello()
+    }
+}
+```
+
+## Alternative approaches and design tradeoffs
+
+This section describes some alternatives that were considered during design.
+
+The main tradeoff we had to make with the proposed syntax is that in cases when the context is generic, then the use of the
+generic parameter happens before its declaration, e.g (from [Use cases](#use-cases) section):
+
+```kotlin
+context(Monoid<T>) // T is used
+fun <T> List<T>.sum(): T = ...
+//  ^^^ T is declared
+```
+
+We feel that it is not going to present a problem in idiomatic Kotlin code, since type parameters are usually a few and
+named with one uppercase letter, so there is not much need to have auto-completion for them in IDE.
+We can also make IDE smart enough to auto-complete the name in the declaration, if the long name is used in the context
+before being declared.
+
+### Alternative syntax options
+
+* Direct extensions of single-receiver syntax
+  ```kotlin
+  fun <T> (Monoid<T>, List<T>).sum(): T = ...
+  ```
+  Aside from complexity of finding nice syntax that does not interact negatively with other existing and potential
+  features of the language, this option does not make it possible to syntactically distinguish the object of the action
+  and the additional context of the action.
+
+* Extension block
+  ```kotlin
+  extension Monoid<T> {
+      fun List<T>.sum(): T = ...
+  }
+  ```
+  The nice part of it that is serves a double-duty of addressing the extension grouping request from
+  [KT-5670](https://youtrack.jetbrains.com/issue/KT-5670), but it is quite verbose for all the contextual use cases,
+  forcing an additional indentation level.
+
+* Context on the right-hand side of function declaration
+  ```kotlin
+  fun <T> List<T>.sum(): T context(Monoid<T>) = ...
+  ```
+  This placement would be consistent with Kotlin's `where` clause, but it is not consistent with receivers being specified
+  before the function name. Moreover, Kotlin has a syntactic tradition of matching declaration syntax and call-site syntax
+  and a context on a call-site is established before the function is invoked.
+
+### Alternative keywords
+
+We've considered a number of alternative keywords.
+
+* `with` (save as scope function to introduce receiver into scope)
+  * Note: reusing the same name will make it confusing in discussions
+* `using` (Scala name, but in Kotlin may clash with use)
+* `given` (will be confusing as Scala uses it for an opposite thing)
+* `implicit` (very different thing in Scala)
+* Meaning "inside of the additional receiver class or its context/scope"
+  * `within`
+  * `inside`
+  * Note: functions with additional receivers are not really inside, they don't see private
+* Meaning "in the context/scope of the receiver class"
+  * `incontext`
+  * `inscope`
+  * **`context` — our choice**
+  * `receiver`
+  * Highlights implicitness & the fact that they are required
+* Meaning "requiring/getting instance of the receiver class"
+  * `having`
+  * `receiving`
+  * `taking`
+  * `utilizing`
+  * `obtaining`
+  * `including`
+
+The choice of `context` was largely driven by its clear use in the prose, as it is quite natural to talk about
+"contextual functions" and other contextual abstractions, hence the keyword also fits well.
+
+### Parentheses vs angle brackets
+
+One of the big decisions around design was choosing between parentheses `context(Ctx)` and angle brackets `context<Ctx>`.
+Here is the summary of benefits we've found for these two options:
+
+* `context<Ctx>` syntax is consistent with how types are passed as arguments in Kotlin calls. 
+  If you have a `Type`, then you pass the corresponding type argument in angle brackets as in 
+  `foo<Type>()`, compare this to passing a class in `foo(Type::class)`. The same is true in annotations,
+  although annotations with type parameters are rarely used in Kotlin code due to their JVM interop limitations.
+  The notable exception is [Android Parcelize](https://developer.android.com/kotlin/parcelize) where you
+  could find annotations like`@TypeParceler<ExternalClass, ExternalClassParceler>()`. Angle brackets 
+  make this analogy of using a type stand out.
+* `context(Ctx)` syntax is consistent with Kotlin parameter declarations. When you declare a function
+  with a context receiver, as in `context(Ctx) fun foo(param: Param)`, you actually declare an additional 
+  anonymous parameter to a function of type `Ctx`. This analogy becomes especially notable when you 
+  consider that the functional type of this declaration, as explained in the [Functional types](#functional-types) section,  
+  is equivalent to `(Ctx, Param) -> Unit`. Parentheses make this analogy of declaring a parameter stand out. 
+
+> Another advantage of the angle brackets syntax is that it makes [Backwards compatibility](#backwards-compatibility) 
+> concerns go away completely, but they are so minor for parentheses anyway, that we did not pay much attention to
+> this difference.
+
+By themselves, these differences do not conclusively point to a choice of which syntactic option is better. 
+In the end, the decision was swayed in favor of parentheses, 
+because this syntax leaves more doors open for potential future extensions and refinements:
+
+* If we find compelling use-cases, we can naturally add support for named context receivers via 
+  `context(name: Ctx)` syntax similarly to named function parameters. 
+* If we ever find "type parameter use before declaration" problematic in practice, as explained in 
+  the beginning of the [Alternative approaches and design tradeoffs](#alternative-approaches-and-design-tradeoffs) section, 
+  the parentheses syntax lends itself to support type parameter introduction before its use
+  directly in the `context` parameter declaration as `context<T>(Monoid<T>)`.
+* If we ever find the need to support modifiers on context receivers, they will most likely be shared with 
+  parameters, due to parameter-like nature of context receivers, as in hypothetical `context(inline Ctx)`.
+
+### Context keyword ambiguities
+
+To avoid potential [Backwards compatibility](#backwards-compatibility) problems in the future with parentheses 
+we've considered making new syntax unambiguous everywhere (including function bodies) via additional syntax, 
+like `@context(Ctx)`,  `context:(Ctx)`,  `context@(Ctx)`, or `context.(Ctx)`. 
+None of the alternatives looked nice or natural.
+
+### Named context receivers
+
+We've looked at various ways to add names to the context receives as an alternative to the qualified `this` syntax
+for [Referencing specific context receiver](#referencing-specific-context-receiver). The leading syntactic option
+considered was `context(name: Type)` similarly to named function parameters.
+
+However, we did not find enough compelling use cases yet to support such naming, as context receivers are explicitly
+designed for something that should be brought into the context, as opposed to a declaration that should be explicitly
+referred to by name. Moreover, we do support disambiguation of multiple context receivers using a type-alias if needed.
+For cases where you need to bring a named thing into the context, there is a workaround.
+
+Consider an example where you want to bring some `callParameters: Map<String, String>` property into the context of
+certain functions in your backend application. If using `context(callParameters: Map<String, String>)` was supported,
+it would create a middle-ground concept that, on one hand, should not be brought into scope as a receiver, because
+the `Map` interface has lots of methods and is not designed to be used like that, but, on the other hand,
+should be implicitly passed down the call chain without syntactic overhead.
+
+Still, you want it named in the context and available for use. A proposed solution is to write the following interface:
+
+```kotlin
+interface CallScope {
+    val callParameters: Map<String, String>
+}
+```
+
+Now, all the relevant functions can declare `context(CallScope)` to get access to the `callParameters` property.
+
+### Multiple receivers with decorators
+
+We've looked at a way to combine contextual receivers with decorators into a single feature. Decorators is a potential
+future Kotlin feature designed to aid and reduce the amount of magic in typical aspect-oriented programming approaches.
+A decorator is a function that wraps another function's body with its code, for example:
+
+```kotlin
+// Declaring transactional decorator
+decorator fun transactional(block: Transaction.() -> Unit) {
+    beginTransation.use { tx ->
+        tx.block()
+    } // Closes transaction at the end    
+}
+
+@transactional // Use decorator to wrap function's body
+fun updateUserSession() {
+    val session = loadSession()
+    session.lastAccess = now()
+    storeSession(session)
+}
+```
+
+This way, the decorator also introduces an additional receiver into the function body and thus can serve as a syntax for
+functions with multiple receivers.
+
+However, semantics of declaration-only decorators (e.g. when `fun updateUserSession()` is a part of an interface) are
+harder to define consistently. A generic decorator, that would support bringing any context receiver into scope
+(e.g. `with` decorator function) will result in harder-to-read use code (something like
+`@with<Transaction> fun updateUserSession` was considered). Moreover, bringing additional receivers into scope via
+decorators does lend itself to clean separation from the regular extension receiver and to tweaks in the
+[Resolution algorithm](#resolution-algorithm) for those additional receivers, such as declaring multiple contexts
+without introducing order between them and making sure that context receivers do not otherwise affect the meaning of
+unqualified `this` expression.
+
+## Future work
+
+This section lists enhancements that are being prototyped, discussed, or otherwise being considered and are potentially
+possible in the future. Feel free to share your ideas in discussion [KEEP-259](https://github.com/Kotlin/KEEP/issues/259).
+
+### Reflection design
+
+Kotlin reflection will have to support the concept of context receivers and represent them in a similar way to dispatch
+and extension receivers. The detailed design for reflection is to be done later.
+
+### Contextual delegated properties
+
+The natural extension is to allow operator functions `getValue`, `setValue`, and `provideDelegate` of
+[Kotlin delegated properties convention](https://kotlinlang.org/docs/delegated-properties.html) to be contextual.
+That former two would allow, for example, using delegation to define transactional properties that can be accessed
+only in a context of transaction:
+
+```kotlin
+class TransactionalVariable<T> {
+    context(Transaction)
+    operator fun getValue(thisRef: Any?, property: KProperty<*>): T { ... }
+  
+    context(Transaction)
+    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: T) { ... }
+}
+
+// Only available for get/set in a context of Transaction
+val userName by TransactionalVariable<String>()
+```
+
+### Local contextual functions and properties
+
+The current design excludes local functions and properties, because they add technical complications without bringing
+substantial benefits. However, supporting them would be a natural future extension. We'll have to design a plan for
+dealing with minor [Backwards compatibility](#backwards-compatibility) problems that would arise, some existing uses
+of the context name will have to be deprecated.
+
+### Callable references to contextual functions
+
+Support for callable references to contextual functions will need a resolution algorithm that is similar to how
+references to global functions are resolved, and unlike references to functions with a receiver:
+
+```kotlin
+context(LoggingContext)
+fun performSomeBusinessOperation(withParams: Params) { ... }
+
+::performSomeBusinessOperation // Will have type of context(LoggingContext) (Params) -> Unit
+```
+
+Currently, we don't have compelling use cases and plans to support special syntax for bound references to
+contextual functions (similarly to functions with a receiver). One can always use a lambda, e.g.
+
+```kotlin
+val op: (Params) -> Unit =
+    { params -> with(createLoggingContext()) { performSomeBusinessOperation(params) } }
+```
+
+### Removing context receiver from the scope with DslMarker
+
+Kotlin has a [`@DslMarker`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-dsl-marker/) annotation designed for DSLs.
+It is mainly designed to work with [Kotlin builders](#kotlin-builders) which should still be written using extension
+receivers as opposed to contextual receivers. However, it might be potentially useful to support `@DslMarker` annotations
+on contextual receivers for [Other Kotlin DSLs](#other-kotlin-dsls) if the corresponding use cases arise in the future.
+
+### Scope properties
+
+To call the contextual function, we need the required set of receivers to be brought in the caller scope, which can be
+done via scope functions `with`, `run`, or `apply`. However:
+
+* They add an extra pair of curly braces increasing the number of nested scopes and indentation levels.
+* They can be used only inside the function scope, while we might want to add a receiver in a class or even file scope.
+
+We consider the future introduction of **scope properties** — a lighter-weight approach to bring a context receiver into
+a scope with the regular property declaration syntax using `with` as a new keyword.
+
+```kotlin
+class Service {
+    with val serviceContext = createServiceContext() // Introduce the scope property with the service context
+
+    fun doSomething() {
+        // serviceContext is a context receiver inside the scope of the class, need not be named explicitly
+    }
+}
+```
+
+It is possible to gradually turn `with` into a hard keyword to support even more concise syntax for bringing
+annonymous receivers into the scope in a class:
+
+```kotlin
+class Service {
+    with createServiceContext() // Introduce anonymous scope property
+}
+```
+
+And, potentially, the same for the local scope 
+(expanding on [Algebraic effects and coeffects](#algebraic-effects-and-coeffects) example):
+
+```kotlin
+fun helloToConsole() {
+    with Emit { msg -> println(msg) }
+    hello()
+}
+```
+
+The detailed design for scope properties is to be presented later.
+
+### Contextual classes and contextual constructors
+
+> We included contextual classes and contextual constructors in the [prototype](#prototype) implemented in Kotlin 1.6.20-M1.
+
+Contextual classes and contextual constructors are yet another natural future extension of this proposal.
+They can be used to require some context to be present for instantiating the class, which has a bunch of use cases.
+
+```kotlin
+context(ServiceContext)
+class Service {
+    fun doSomething() {
+        // declarations from ServiceContext are available here
+    }
+}
+```
+
+With the [scope properties](#scope-properties) feature in mind, the above declaration will get desugared to:
+
+```kotlin
+class Service
+     // Constructor is contextual, needs ServiceContext when it is being invoked
+     context(ServiceContext) 
+     constructor() {} 
+
+     with this@ServiceContext // capture constructor's param into a scope property
+
+     fun doSomething() {
+         // declarations from ServiceContext are available here
+     }
+}
+```
+
+### Future decorators
+
+While we've decided to not rely on decorators for the core support of multiple receivers as explained in the
+[Multiple receivers with decorators](#multiple-receivers-with-decorators) section, the very concept of decorators is
+a useful one with its own use cases. Moreover, the concept of context receiver and the corresponding changes to the resolution
+rules to account for them is an important building block for decorators in the future.
+
+It is important for readability of code written in the Kotlin language to be clear on the meaning of unqualified `this`.
+Consider the example decorated function declaration:
+
+```kotlin
+@transactional // Use decorator to wrap function's body
+fun updateUserSession() { ... }
+```
+
+If `updateUserSession` is a top-level function, it should not have any `this` reference. If it is a member function, then
+`this` inside the function shall refer to an instance of its container class. A decorator, such as `@transaction`, even
+if it adds some declarations to the scope of the function's body, should not be empowered to change the meaning of `this`
+inside of it. The concept of context receiver is such a mechanism.
+
+### Unified context properties
+
+Frameworks, libraries, and applications sometimes need to pass various ad hoc local properties throughout the function
+call-chains. When a property is used by many functions in the call-chain, then it makes sense to define a dedicated
+context interface and explicitly declare all affected functions as contextual. For example, if most functions in our
+application need and use some kind of global configuration property, then we can declare the corresponding interface
+and mark all the functions in our app with `context(ConfigurationScope)`.
+
+```kotlin
+interface ConfigurationScope {
+    val configuration: Configuration
+}
+```
+
+The situation is different when an application uses lots of properties like that, but each function typically uses none or
+a few. Examples include authentication information, distributed call tracing, styling properties, etc. 
+
+If we model each property as a separate context interface, then the `context(...)` declarations will quickly get
+out of hand. Moreover, it becomes hard to add a new property somewhere deep down the call-chain, as the corresponding
+context needs to be passed through the whole call-stack. Another solution is to create an "uber context", which combines
+all the contextual properties any piece of the code might need, but this might be impossible in a big modular application,
+as specific properties can be local to a module or even local to a few functions in a larger module.
+
+A popular modular solution to pass such context properties is to use
+[ThreadLocal](https://docs.oracle.com/javase/8/docs/api/java/lang/ThreadLocal.html) variables. However, thread-locals
+are bound to a thread, so any framework whose execution context spans multiple threads must introduce its own solution,
+like [CoroutineContext](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/-coroutine-context/) in Kotlin coroutines,
+[CompositionLocal](https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal) in Jetpack Compose,
+[Context](https://projectreactor.io/docs/core/release/api/reactor/util/context/Context.html) in Project Reactor, etc.
+This is challenging for any code that uses several such frameworks together as it is not trivial to ensure preservation
+of the context properties when execution spans multiple frameworks. It can also get verbose in the frameworks themselves,
+as this context has to be manually passed through the framework code.
+
+If we focus on Kotlin-specific frameworks, then we see that each of them has a framework-specific mechanism to pass
+the context around:
+
+* [CompositionLocal](https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal) variables
+  are passed down the call-chain only via `@Composable` functions.
+* [CoroutineContext](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/-coroutine-context/) elements
+  are passed down the call-chain only via `suspend` functions.
+
+When you call a regular function, the context is lost. When you call a suspending function from a composable function,
+for example, then the context is lost, too. However, there are use cases where it is convenient to have a unified
+`ThreadLocal`-like approach to context properties that can be passed though different types of functions.
+
+A potential future solution is to declare a unified context properties framework in the Kotlin standard library, so that,
+first and foremost, it can be used with regular functions, for example:
+
+```kotlin
+val contextUser = contextProperty<User?>(null)
+
+context(PropertiesScope) // Can access context properties
+fun authenticate() {
+    val currentUser = contextUser.current // Retrieve from context
+    // ...
+}
+```
+
+Also, `suspend` and `@Composable` functions can be retrofitted to work as if they are declared with
+`context(PropertiesScope)` modifier and so will pass a set of current context properties via their calls,
+ensuring interoperability of the corresponding mechanisms.
+                               
+## Open issues and concerns
+
+This section lists known issues with this proposal that should be mitigated or accepted and weighed against
+the benefits this proposal brings.
+
+### Context receivers abuse and scope pollution
+
+Kotlin code may suffer from proliferation of implicit receivers in code. In the worst case, all implicit receivers 
+have to be checked to resolve the call during compilation. With many implicit receivers in scope human readers
+might also find it hard to figure it out where the declaration that code is using comes from. 
+
+```kotlin
+class AClass { // this: AClass 
+    fun Extension.doSomething() { // this: Extension
+       dsl1 { // this: Builder1
+           dsl2 { // this: Builder2
+               foo() // where is this function declared? 
+           }
+       }    
+    }    
+}
+```
+
+Currently, a single pair of nested curly braces `{...}`, being it a class, function, or a lambda, may add at 
+most one implicit receiver into scope. This naturally limits proliferation of implicit receivers. You can have at
+most as many implicit receivers in scope as the nesting level of your code.
+
+Introducing context receivers makes it possible to add multiple implicit receivers into scope per one nesting level,
+removing this natural limitation. If abused, this will make compilation slow (by having to scan move implicit receivers)
+and understanding code harder.
+
+The [contexts and coding style](#contexts-and-coding-style) section gives some naming rules and other advice
+designed to mitigate potential abuse of context receivers.
+
+### Methods from Any in top-level functions
+
+Counterintuitively, the following code will compile in this design:
+
+```kotlin
+context(LoggingContext)
+fun weirdToString(): String = toString() // OK
+```
+
+However, the following code will not compile (due to resolution ambiguity):
+
+```kotlin
+context(LoggingContext, Transaction)
+fun weirdToString(): String = toString() // ERROR
+```
+                                                              
+This is an effect of treating context receivers more or less like all other implicit receivers in Kotlin, 
+but bundling them into a single group in the [Resolution algorithm](#resolution-algorithm).
+
+All the methods defined on the [`Any`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/) type 
+(like `toString`, `equals`, `hashCode`) are available on any Kotlin class and 
+thus are also available in any function with a receiver, for example:
+
+```kotlin
+fun LoggingContext.weirdToString(): String = toString() // also OK
+```
+
+Context receivers do not create an entirely new problem here, but make an existing problem more pronounced. 
+One can find legal use cases for `Any` methods on an extension receiver, but we don't know any
+sensible use cases with context receivers, so their availability is an unwanted side effect for top-level 
+contextual functions. 
+
+# Prototype
+
+The first prototype of context receivers is available in Kotlin 1.6.20-M1 under the `-Xcontext-receivers` compiler option.
+Note that the implementation is experimental and IDE support is minimal. 
+Feel free to report any issues you face in [YouTrack](https://kotl.in/issue).
diff --git a/proposals/definitely-non-nullable-types.md b/proposals/KEEP-0268-definitely-non-nullable-types.md
similarity index 100%
rename from proposals/definitely-non-nullable-types.md
rename to proposals/KEEP-0268-definitely-non-nullable-types.md
diff --git a/proposals/enum-entries.md b/proposals/KEEP-0283-enum-entries.md
similarity index 100%
rename from proposals/enum-entries.md
rename to proposals/KEEP-0283-enum-entries.md
diff --git a/proposals/data-objects.md b/proposals/KEEP-0317-data-objects.md
similarity index 100%
rename from proposals/data-objects.md
rename to proposals/KEEP-0317-data-objects.md
diff --git a/proposals/subclass-opt-in-required.md b/proposals/KEEP-0320-subclass-opt-in-required.md
similarity index 100%
rename from proposals/subclass-opt-in-required.md
rename to proposals/KEEP-0320-subclass-opt-in-required.md
diff --git a/proposals/break-continue-in-inline-lambdas.md b/proposals/KEEP-0326-break-continue-in-inline-lambdas.md
similarity index 100%
rename from proposals/break-continue-in-inline-lambdas.md
rename to proposals/KEEP-0326-break-continue-in-inline-lambdas.md
diff --git a/proposals/references-to-java-synthetic-properties.md b/proposals/KEEP-0328-references-to-java-synthetic-properties.md
similarity index 100%
rename from proposals/references-to-java-synthetic-properties.md
rename to proposals/KEEP-0328-references-to-java-synthetic-properties.md
diff --git a/proposals/context-receivers.md b/proposals/context-receivers.md
index b71f7180d..614c19e7d 100644
--- a/proposals/context-receivers.md
+++ b/proposals/context-receivers.md
@@ -1,1371 +1 @@
-# Context receivers
-
-* **Type**: Design proposal
-* **Authors**: Roman Elizarov, Anastasia Shadrina
-* **Contributors**: Denis Zharkov, Marat Akhin, Mikhail Belyaev, Ilya Gorbunov, Ilmir Usmanov, Simon Ogorodnik,
-  Dmitriy Novozhilov, Mikhail Glukhikh
-* **Status**: Experimental in 1.6.20-M1
-* **Discussion**: [KEEP-259](https://github.com/Kotlin/KEEP/issues/259)
-* **Prototype**: Implemented
-
-## Abstract
-
-This is a design proposal for support of context-dependent declarations in Kotlin. 
-It covers a large variety of use cases and was previously known and requested under the name of
-"multiple receivers", see [KT-10468](https://youtrack.jetbrains.com/issue/KT-10468).
-
-We would appreciate hearing your feedback on this proposal in the [KEEP-259](https://github.com/Kotlin/KEEP/issues/259).
-
-## Table of Contents
-
-<!--- TOC -->
-
-* [Introduction](#introduction)
-  * [Context receivers and contextual declarations](#context-receivers-and-contextual-declarations)
-  * [Goals](#goals)
-* [Detailed design](#detailed-design)
-  * [Contextual functions and property accessors](#contextual-functions-and-property-accessors)
-  * [Functional types](#functional-types)
-  * [Referencing specific receiver](#referencing-specific-receiver)
-  * [Resolution algorithm](#resolution-algorithm)
-  * [Backwards compatibility](#backwards-compatibility)
-  * [JVM ABI and Java compatibility](#jvm-abi-and-java-compatibility)
-* [Use cases](#use-cases)
-* [Contexts and coding style](#contexts-and-coding-style)
-  * [Overloading by the presence of context](#overloading-by-the-presence-of-context)
-  * [Performing an action on an object](#performing-an-action-on-an-object)
-  * [Providing additional parameters to an action](#providing-additional-parameters-to-an-action)
-  * [Providing additional context for an action](#providing-additional-context-for-an-action)
-  * [Kotlin builders](#kotlin-builders)
-  * [Other Kotlin DSLs](#other-kotlin-dsls)
-  * [Designing context types](#designing-context-types)
-* [Similar features in other languages](#similar-features-in-other-languages)
-  * [Scala given instances and using clauses](#scala-given-instances-and-using-clauses)
-  * [Algebraic effects and coeffects](#algebraic-effects-and-coeffects)
-* [Alternative approaches and design tradeoffs](#alternative-approaches-and-design-tradeoffs)
-  * [Alternative syntax options](#alternative-syntax-options)
-  * [Alternative keywords](#alternative-keywords)
-  * [Parentheses vs angle brackets](#parentheses-vs-angle-brackets)
-  * [Context keyword ambiguities](#context-keyword-ambiguities)
-  * [Named context receivers](#named-context-receivers)
-  * [Multiple receivers with decorators](#multiple-receivers-with-decorators)
-* [Future work](#future-work)
-  * [Reflection design](#reflection-design)
-  * [Contextual delegated properties](#contextual-delegated-properties)
-  * [Local contextual functions and properties](#local-contextual-functions-and-properties)
-  * [Callable references to contextual functions](#callable-references-to-contextual-functions)
-  * [Removing context receiver from the scope with DslMarker](#removing-context-receiver-from-the-scope-with-dslmarker)
-  * [Scope properties](#scope-properties)
-  * [Contextual classes and contextual constructors](#contextual-classes-and-contextual-constructors)
-  * [Future decorators](#future-decorators)
-  * [Unified context properties](#unified-context-properties)
-* [Open issues and concerns](#open-issues-and-concerns)
-  * [Context receivers abuse and scope pollution](#context-receivers-abuse-and-scope-pollution)
-  * [Methods from Any in top-level functions](#methods-from-any-in-top-level-functions)
-* [Prototype](#prototype)
-
-<!--- END -->
-
-## Introduction
-
-Consider an interface `Scope` that represents some context and another interface `Entity` that we want to define an
-action on, so that this action is available only in a context that provides an instance of a `Scope`, without having to
-explicitly pass the `Scope` around.
-
-In Kotlin, you can define such a context-restricted declaration using a
-[member extension function](https://kotlinlang.org/docs/extensions.html#declaring-extensions-as-members).
-A member extension has two receivers: a dispatch receiver from the class and an extension receiver from the method's extension.
-
-```kotlin
-interface Entity
-
-interface Scope { // Scope is a dispatch receiver
-    fun Entity.doAction() { // Entity is an extension receiver for doAction
-        ...
-    }
-}
-```
-
-> A real-life example of a `Scope` could be [`CoroutineScope`](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/),
-> from the [`kotlinx.coroutines`](https://github.com/Kotlin/kotlinx.coroutines) library. You must provide a `CoroutineScope`
-> to be able to launch new coroutines as a part of an action. A real-life example of an `Entity` could be a
-> [`Flow`](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html)
-> with an operation to launch a coroutine that collects a flow.
-
-When calling a `doAction` member extension function, its dispatch receiver `Scope` must be present in the caller's scope.
-There is no dedicated syntax to explicitly specify a dispatch receiver for such a call. On the other hand, the extension
-receiver `Entity` can and is usually specified explicitly using `entity.doAction()` qualified call syntax.
-To specify a `Scope` dispatch receiver we can use a **scope function**, like
-[with](https://kotlinlang.org/docs/scope-functions.html#with), [run](https://kotlinlang.org/docs/scope-functions.html#run),
-or [apply](https://kotlinlang.org/docs/scope-functions.html#apply), to bring it into scope:
-
-```kotlin
-with(scope) {
-    entity.doAction()
-}
-```
-
-We say that an extension receiver defines the **object of an action**, while a dispatch receiver effectively serves as
-an implicit parameter that must be present in the caller's scope but cannot be specified explicitly. Thus, a member
-extension function can be called a context-dependent function, and a dispatch receiver represents the **context of an action**.
-
-The context-oriented approach has many applications in the design of idiomatic Kotlin APIs (for example, see
-["An introduction to context-oriented programming in Kotlin" by Alexander Nozik](https://proandroiddev.com/an-introduction-context-oriented-programming-in-kotlin-2e79d316b0a2))
-and is a building block of a more generic [code coloring concept](https://github.com/Kotlin/KEEP/blob/master/notes/code-coloring.md).
-However, a member extension is now the only way to define a context-dependent declaration, and this form has
-multiple limitations that restrict its practical usefulness.
-
-The key one is that a **member extension cannot be declared on a third-party class**. It limits the ability to decouple,
-modularize and structure APIs in larger applications. The only way to introduce a context-dependent `Entity.doAction`
-extension is to write it as a member of a `Scope`, which is not always appropriate from a modularity standpoint.
-
-> For example, in the `kotlinx.coroutines` library, it would be inappropriate to declare a `Flow.launchFlow()` extension as
-> a member of `CoroutineScope`, because `CoroutineScope` is a more general concept and its declaration shall not depend
-> on a more specific concept like `Flow`.
-
-Another limitation is that **a member extension is always the extension**. An extension function in Kotlin has an option
-of being called with qualified syntax as in `entity.doAction()`. This is a stylistically appropriate syntax when an
-action is performed on an entity. However, some functions don't operate on a specific entity and should not be declared
-as such. There is no way to declare a top-level function to be called as `doAction()` that would require the presence of
-a specific context in scope.
-
-> Use cases for that come a lot. For example, it would be helpful to be able to define a `TransactionScope` and have
-> syntax to declare transactional functions that have a requirement of being called only in a `TransactionScope`, but
-> forbid an explicit `transaction.doSomething()` call, since they do not work **on** a transaction, but **in the context of**
-> a transaction. 
-
-The final limitation of providing context with a member extension is that **only one receiver can represent a context**.
-It limits composability of various abstractions, as we cannot declare a function that must be called only within two
-or more scopes present at the same time.
-
-> For example, there might be a need to define a function that requires a `CoroutineScope` to be able to launch a
-> coroutine and requires a `TransactionScope` at the same time.
-
-### Context receivers and contextual declarations
-
-This proposal introduces the syntax for defining context-dependent declarations with special **context receivers**.
-This feature overcomes highlighted limitations and covers a variety of use cases.
-
-The context here is not directly related to the action but is used by the action. It can provide additional operations,
-configuration, or execution context. A good example of context would be `Comparator`, `CoroutineScope`, some kind of
-`Transaction` or `LoggingContext` (see [Use cases](#use-cases) for details).
-A simple **contextual function** is declared like this:
-
-```kotlin
-context(Scope)
-fun Entity.doAction()
-```
-
-A top-level contextual function can also be declared:
-
-```kotlin
-context(Scope)
-fun doAction()
-```
-
-Its key difference from the `Scope.doAction` extension is that it cannot be called with a qualified `scope.doAction()`
-syntax, and it has no `this` reference inside its body, since it has no object on which it performs its action.
-Moreover, there can be multiple context receivers. See [Detailed design](#detailed-design) section.
-
-### Goals
-
-* Remove all limitations of member extensions for writing contextual abstractions
-    * Support top-level (non-member) contextual functions and properties
-    * Support adding contextual function and properties to 3rd party context classes
-    * Support multiple contexts
-* Make blocks of code with multiple receivers representable in Kotlin's type system
-* Separate the concepts of extension and dispatch receivers from the concept of context receivers
-    * Context receivers should not change the meaning of unqualified `this` expression
-    * Multiple contexts should not be ordered during resolution, resolution ambiguities shall be reported
-* Design a scalable resolution algorithm with respect to the number of receivers
-    * Call resolution should not be exponential in the number of context receivers
-
-## Detailed design
-
-A context requirement for a declaration is expressed by a new modifier with the `context` keyword 
-followed by the list of context receiver types in parenthesis. The list can contain one or more comma-separated types
-(a trailing comma is supported, too, for use in multi-line declarations).
-
-```kotlin
-context(A, B, C)
-```
-
-> As a matter of coding style, context receivers are defined after annotations and before other modifiers
-> on a separate line.
-
-The following types of declarations can be contextual:
-
-* Functions (top-level, member, extensions functions are currently supported)
-* Property getters and setters (of all these kinds, too)
-
-The types listed as context receivers of a declaration are not allowed to repeat, and no pair
-of them is allowed to have a subtype relation between them.
-
-> This constraint comes from the greedy nature of the [Resolution algorithm](#resolution-algorithm) and absence
-> of any way to explicitly pass context arguments into a call. 
-
-> In the current [prototype](#prototype) implemented in 1.6.20-M1, you won't receive an error on a declaration-site 
-> if there are repeated context receivers. The compiler will report an error only on a call-site.
-
-### Contextual functions and property accessors
-
-For functions and property accessors, context receivers are additional **context parameters** of those
-declarations. They differ from regular parameters in that they are anonymous and are passed
-implicitly just like receivers. 
-In the body of the corresponding function or property accessor they bring the corresponding arguments 
-into the body scope as implicit receivers for further calls.
-
-Take a look at the following example.
-
-```kotlin
-context(Comparator<T>)
-infix operator fun <T> T.compareTo(other: T) = compare(this, other)
-
-context(Comparator<T>)
-val <T> Pair<T, T>.max get() = if (first > second) first else second
-```
-
-* In the first declaration, `compare` is resolved to `Comparator.compare`, because `Comparator<T>` is a context receiver.
-* In the second declaration, the expression `first > second` calls the previously defined operator function `compareTo`, because
-  `Comparator<T>` is a context receiver and can be implicitly passed to `compareTo` as its context parameter.
-
-If a function or a property accessor is a member of some class or interface and has context receivers, then its
-overrides must have context receivers of the same types.
-
-```kotlin
-interface Canvas
-
-interface Shape {
-    context(Canvas)
-    fun draw()
-}
-
-class Circle : Shape {
-    context(Canvas)
-    override fun draw() {
-      ...
-    }
-}
-```
-
-> No widening of context types is allowed on override, context receivers are very similar to function 
-> parameters in this respect.
-
-### Functional types
-
-The functional type of a contextual function can be denoted with the same modifier `context(...)`, which
-should be present at the beginning of the functional type signature.
-
-```kotlin
-typealias ClickHandler = context(Button) (ClickEvent) -> Unit
-```
-
-In the type system, the functional type with context receivers (just as the functional type with an ordinary receiver)
-is equivalent to the similar type having all context receiver types as the types of additional arguments. The resulting
-signature of the functional type replicates the textual order in which every argument appears. It means:
-
-* The type `context(C1, C2) R.(P1, P2) -> T` will actually turn into an instance of the type constructor
-  `Function5<C1, C2, R, P1, P2, T>`.
-
-* Such assignments are valid:
-  ```kotlin
-  fun main() {
-    var g: context(Context) Receiver.(Param) -> Unit
-    g = ::foo         // OK
-    g = ::bar         // OK
-    g = Receiver::baz // OK
-  }
-  
-  fun foo(context: Context, receiver: Receiver, p: Param) {}
-
-  context(Context)
-  fun bar(receiver: Receiver, p: Param) {}
-
-  context(Context)
-  fun Receiver.baz(p: Param) {}
-  ```
-  
-Conceptually, context receivers of a declaration have no order. However, a signature of a contextual functional type 
-replicates the textual order they are declared in. We consider the future introduction of automatic conversion between 
-two similar functional types that differ only in the order of context receivers (for example, `context(A, B) () -> Unit`
-and `context(B, A) () -> Unit`). In 1.6.20, it won't be supported. 
-
-> In the current [prototype](#prototype), you can invoke a contextual functional type only by passing all receivers 
-> (including an extension receiver) as arguments explicitly. For example:
-> ```kotlin
-> context(C)
-> fun R.f(g: context(C) R.(Param) -> Unit, p: Param) {
->     g(this@C, this@R, p)
-> }
-> ```
-> 
-
-### Referencing specific receiver
-
-Context receivers can never be referenced using a plain `this` expression and never change the meaning of `this`.
-However, this proposal introduces another option to reference a receiver of any type, including context one, via the
-[labeled `this` expression](https://kotlinlang.org/docs/reference/grammar.html#THIS_AT).
-For every receiver in the scope, the compiler generates the label from the name of its type with the following rules:
-
-* If the receiver type is parenthesized, parentheses are omitted
-* If the receiver type is nullable, the question mark is omitted
-* If the receiver type has type arguments or type parameters, they are omitted
-* If the receiver type is a type alias or class, the label is generated from its short name without type parameters
-* If the receiver type is functional, no label is generated
-
-```kotlin
-context(Logger, Storage<User>)
-fun userInfo(name: String): Storage<User>.Info {
-    this@Logger.info("Retrieving info about $name")
-    return this@Storage.info(name)
-}
-```
-
-> Note that referencing a receiver via a labeled `this` expression is now supported only by the compiler.
-> Full IDE plugin support is planned to be implemented soon.
-
-If multiple receivers have the same generated label, none of them can be referenced with the qualified `this`.
-In cases where the label cannot be generated or referenced, a workaround is to use a type alias.
-
-```kotlin
-typealias IterableClass<C, T> = (C) -> Iterator<T>
-
-context(IterableClass<C, T>)
-operator fun <C, T> C.iterator(): Iterator<T> = this@IterableClass.invoke(this)
-```
-
-Using labeled `this` may come in handy even without context receivers. If multiple receivers in a nested scope can be 
-addressed via plain `this`, the use of it becomes ambiguous and decreases readability. Using a bare type name rather 
-than a function name for a label looks more natural since the object type describes the object better than the scope it 
-belongs to ([KT-21387](https://youtrack.jetbrains.com/issue/KT-21387)).
-
-```kotlin
-fun List<Int>.decimateEveryEvenThird() = buildSequence {
-    var counter = 1
-    for (e in this@List) {
-        if (e % 2 == 0 && counter % 3 == 0) {
-            yield(e)
-        }
-        counter += 1
-    }
-}
-```
-
-### Resolution algorithm
-
-The current Kotlin call resolution algorithm is documented in the [Kotlin specification](https://kotlinlang.org/spec/overload-resolution.html#overload-resolution). Contextual receivers introduce a number of changes.
-
-For the purpose of call resolution, context receivers in the scope are considered with all the other implicit receivers in scope. However, they don't have a total hierarchy like other implicit receivers that come from nested syntactic structures.
-Instead, they form non-overlapping groups according to the affected scope. 
-There is no actual order inside groups, but groups themselves are sorted in the scope order: 
-from the innermost to the outermost.
-
-When selecting a candidate of the call, the context parameters of the candidates are initially ignored. Only extension
-and dispatch receivers participate in the algorithm of candidate selection.
-
-> This and other features explained below ensure that the algorithm is not exponential 
-> with respect to the number of context receivers in the function declaration.
-
-When looking for candidates, the whole group of context receivers is processed.
-Multiple applicable candidates in the same group result in ambiguity. If a suitable candidate is found in some group, name resolution ends. In the initially proposed
-implementation, we only consider (non-local) contextual function and properties, so there could be only one group of
-contexts in a scope.
-
-```kotlin
-class A {
-    context(B1, B2)
-    fun C.f() { 
-       // A group: [B1, B2] 
-       with (d) { // Add receiver to the scope
-           // Resolution order: d -> C -> A -> [B1, B2] -> imports
-       }  
-    }
-}
-```
-
-When the candidate target of a call has context requirements itself, those requirements are resolved greedily.
-For each context parameter of a candidate, the first implicit receiver with a suitable type is considered to be used as 
-a context argument of the corresponding call. If a type of a declared context parameter of a candidate uses a generic
-type whose value is not determined yet, then the corresponding type constraints are added to the 
-_constraint system_ of this candidate call. If solving this system fails, then the candidate is considered to be inapplicable, 
-without trying to substitute different implicit receivers available in the context.
-
-Candidates with context requirements are considered to be _more specific_ for the purpose of call resolution
-than the same candidates without context requirements.
-
-> Currently, we don't define a specificity relation between candidates having different sets of context parameters
-> for the lack of compelling use cases for doing so. It can be introduced later in a backwards-compatible way
-> if needed.
-
-Further details of this algorithm will be presented as a part of the Kotlin specification revision.
-
-### Backwards compatibility
-
-The `context(Ctx)` syntax for a function modifier may change the meaning of a previously valid code if we add support
-for local contextual functions in the future. For example:
-
-```kotlin
-open class Ctx {
-    companion object : Ctx
-}
-
-fun context(ctx: Ctx) { ... }
-
-fun foo() {
-    context(Ctx) // Invokes function "context" with "Ctx" companion object
-    fun bar() { ... } // Local function bar
-}
-```
-
-It is not a concern in the initially proposed implementation, which does not support local contextual functions and
-properties. To support them in the future we'll have to deprecate such ambiguous uses of user-defined `context` functions.
-However, we could not find any real Kotlin code that will be affected, so a potential impact of such deprecation is
-extremely low.
-
-> We don't need to turn `context` into a hard keyword and forbid using it as a function or property name. It will be
-> a soft-keyword and remain allowed for use as an identifier.
-
-### JVM ABI and Java compatibility
-
-In the JVM, the contextual function is just an ordinary method with an expanded parameter list. Parameters have textual
-order according to the functional type signature: context receivers go right after the dispatch receiver (if present)
-and before the extension receiver (if present). For the contextual property, the same applies to its getter and setter.
-
-Assume the following top-level contextual function signature:
-
-```kotlin
-context(C1, C2)
-fun R.f(p1: P1, p2: P2)
-```
-
-After compilation, it will turn into the following JVM method signature:
-
-```java
-public static final void f(C1 c1, C2 c2, R r, P1 p1, P2 p2)
-```
-
-And you can call it from Java as a regular static member:
-
-```java
-public class TestF {
-    public static void test(C1 c1, C2 c2, R r, P1 p1, P2 p2) {
-        MainKt.f(c1, c2, r, p1, p2);
-    }
-}
-```
-
-## Use cases
-
-Context receivers can be useful in many domains and applications. 
-An assortment of use cases is presented below.
-
-> Most of the use cases are from the [original discussion](https://youtrack.jetbrains.com/issue/KT-10468).
-
-* Injecting loggers and other contextual information into functions and classes
-  ```kotlin
-  interface LoggingContext {
-      val log: Logger // this context provides reference to logger  
-  }
-  
-  context(LoggingContext)
-  fun performSomeBusinessOperation(withParams: Params) {
-      log.info("Operation has started")
-  }
-  ```
-  
-* Calculating density-independent pixels in Android
-  ```kotlin
-  context(View)
-  val Float.dp get() = this * resources.displayMetrics.density
-  
-  context(View)
-  val Int.dp get() = this.toFloat().dp
-  ```
-  
-* Creating JSONs with [JSONObject](https://www.javadoc.io/doc/com.google.code.gson/gson/2.8.5/com/google/gson/JsonObject.html)
-  and custom DSL
-  
-  ```kotlin
-  fun json(build: JSONObject.() -> Unit) = JSONObject().apply { build() }
-
-  context(JSONObject)
-  infix fun String.by(build: JSONObject.() -> Unit) = put(this, JSONObject().build())
-
-  context(JSONObject)
-  infix fun String.by(value: Any) = put(this, value)
-
-  fun main() {
-      val json = json {
-          "name" by "Kotlin"
-          "age" by 10
-          "creator" by {
-              "name" by "JetBrains"
-              "age" by "21"
-          }
-      }
-  }
-  ```
-  
-* Working with mathematical abstractions
-  ```kotlin
-  context(Monoid<T>)
-  fun <T> List<T>.sum(): T = fold(unit) { acc, e -> acc.combine(e) }
-  ```
-  
-* Using structured concurrency
-  ```kotlin
-  context(CoroutineScope)
-  fun <T> Flow<T>.launchFlow() {
-      launch { collect() }  
-  }
-  ```
-  
-* Declaring transactional functions
-  ```kotlin
-  context(Transaction)
-  fun updateUserSession() {
-      val session = loadSession()
-      session.lastAccess = now()
-      storeSession(session)
-  }
-  ```
-  
-* Conveniently scoping automatically closeable resources (flexible “try-with-resources”)
-  ```kotlin
-  interface AutoCloseScope {
-      fun defer(closeBlock: () -> Unit)
-  }
-
-  context(AutoCloseScope)
-  fun File.open(): InputStream
-
-  fun withAutoClose(block: context(AutoCloseScope) () -> Unit) {
-      val scope = AutoCloseScopeImpl() // Not shown here
-      try {
-          with(scope) { block() }
-      } finally {
-          scope.close()
-      }   
-  }
-
-  // usage
-  withAutoClose {
-      val input = File("input.txt").open()
-      val config = File("config.txt").open()
-      // Work
-      // All files are closed at the end
-  }
-  ```
-
-## Contexts and coding style
-
-Addition of context receivers to the language creates a new dimension in the coding style considerations — in what cases
-it is appropriate to use context receivers and what kind of classes or interfaces are best suited for that role.
-
-From the coding style and naming perspective, members and extensions of context receivers shall be treated very much
-like top-level declarations. In fact, context receivers can be viewed as a context-dependent importing mechanism with
-the caveat that they effectively import a number of declarations with a wildcard import `*`.
-Compare the following declaration of a `doSomething` function with an import:
-
-```kotlin
-import mypackage.*
-
-fun doSomething() { ... }
-```
-
-And a similar declaration using a context receiver:
-
-```kotlin
-context(MyContext)
-fun doSomething() { ... }
-```
-
-In both cases, the code in the `doSomething` body can refer to the declarations inside either `mypackage` or
-inside `MyContext` using their short unqualified names. The names of declarations in the corresponding context,
-just like the names of the top-level declarations, must be unambiguous to the maximal extent, to ensure readability
-of the resulting code.
-
-In practice, it means that very few existing classes or interfaces in a typical Kotlin codebase would fit a role of
-a context receiver. A typical class is designed with `instance.member` call-site usage in mind, as in `user.name`.  
-On the other hand, top-level declarations are designed to be used by their short name without a qualifier.
-
-### Overloading by the presence of context
-
-It is tempting to give functions in contextual receivers the same names as the names of existing top-level functions, 
-so that their behavior changes in the specific context. For example, the Kotlin standard library has a top-level
-[`println`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.io/println.html) function, so you can write:
-
-```kotlin
-fun hello() {
-    println("Hello")
-}
-```
-
-The `println` function is also declared in the [`java.io.PrintWriter`](https://docs.oracle.com/javase/8/docs/api/java/io/PrintWriter.html) class.
-By adding `context(PrintWriter)` to the `hello` function declaration, you can change it to 
-start printing to `PrintWriter` without otherwise changing a single line of code inside it:
-
-```kotlin
-context(PrintWriter)
-fun hello() {
-    println("Hello")
-}
-```
-
-It might be a neat trick for a small application, but it is a very error-prone practice for a larger codebase. It becomes 
-all too easy to call other functions from `hello` which also call `println` themselves and to forget about `context(PrintWriter)`:
-
-```kotlin
-context(PrintWriter)
-fun hello() {
-    println("Hello")
-    world()
-}
-
-// forgot the context
-fun world() {
-    println("World")
-}
-```
-
-The above code still compiles (because there is a top-level `println` function) but it does not do what 
-you likely intended it to do. **Don't do this**. 
-
-A rule of thumb is that the names of functions available on the context receivers should be distinct from the 
-functions available at the top-level in your application.
-
-> For the same reason, it is a bad idea to add language support for any kind of default values for contextual receivers,
-as it will make a similar mistake (of forgetting to pass the context along) undetectable during compilation.
-
-### Performing an action on an object
-
-When writing code that performs an action on an object it is customary in Kotlin to refer to their members
-and extensions by their short name. It is possible to be explicit using `this.`, but it is not recommended in Kotlin
-to write in cases when there are no ambiguities. For example, this is how members and extensions are implemented in
-a typical class:
-
-```kotlin
-class User(
-    val name: String,
-    var updateTime: Instant,
-) {
-    fun updateNow() {
-        updateTime = now() // Notice that we don't write this.updateTime here
-    }
-}
-```
-
-To ensure readability it is important to write code so that there is always a single object on which the action
-is performed upon and pass all additional information in explicitly named parameters. This practice is enforced by the
-Kotlin syntax that allows the definition of only a single extension receiver in a function declaration. So, when writing
-extensions that perform an action on an object **don't do this**:
-
-```kotlin
-context(User)
-fun updateNow() {
-    updateTime = now() // BAD STYLE: Don't use a context receiver here
-}
-```
-
-**Do this**:
-
-```kotlin
-fun User.updateNow() {
-    updateTime = now() // GOOD STYLE: Action is performed on an extension receiver
-}
-```
-
-Even though both declarations are similar in many aspects, and their bodies look similar, the declaration of
-`fun User.updateNow()` is explicit about the intent to perform an action on the `User` object.
-
-### Providing additional parameters to an action
-
-When an action takes additional parameters that specify what kind of operation shall happen, the normal Kotlin parameters
-shall be used, for example, **do this**:
-
-```kotlin
-fun User.recordLastLogin(address: InetAddress) {
-    lastLoginAddress = address // GOOD STYLE: passing parameter explicitly
-}
-```
-
-Don't use context parameters as a way to implicitly pass additional parameters, even though it is technically possible.
-**Don't do this**:
-
-```kotlin
-context(InetAddress)
-fun User.recordLastLogin() {
-    lastLoginAddress = this@InetAddress // BAD STYLE: Don't use context as an implict parameter
-}
-```
-
-### Providing additional context for an action
-
-Context receivers shall be used to provide additional, ubiquitous context for actions. As a litmus test, ask yourself
-if that information might have been provided via a global top-level scope in a smaller application
-with a simpler architecture. If the answer is yes, then it might be a good idea to provide it via a context receiver.
-For example, it is a good idea to inject the source of the current time into various time-dependent functions,
-so you might declare a context that provides current time and pass it to time-dependent functions as a context parameter:
-
-```kotlin
-interface TimeSource {
-    fun now(): Instant
-}
-
-context(TimeSource)
-fun updateNow() {
-    updateTime = now() // GOOD STYLE: Use time source from the context
-} 
-```
-
-### Kotlin builders
-
-The following builder pattern is often used in idiomatic Kotlin code:
-
-```kotlin
-fun someObject(builder: SomeObjectBuilder.() -> Unit) =
-    SomeObjectBuilder().run {
-        builder()
-        build()
-    }
-
-// Later in code
-someObject {
-    property = value
-    ...
-}
-```
-
-This builder pattern uses a functional type with an extension receiver `SomeObjectBuilder.() -> Unit` for good and shall
-continue doing so. Conceptually, the code inside `someObject { ... }` block performs an action upon the `SomeObjectBuilder` instance
-and using an extension receiver for this is in style. We do not recommend using context receivers for such simple builders.
-
-However, context receivers make it possible to define _contextual operators_ &mdash; operators that are available 
-only in the context of the corresponding builder, as shown in "Creating JSONs" example in the [Use cases](#use-cases) section.
-This is a legitimate use-case of context receivers for builders. 
-
-### Other Kotlin DSLs
-
-Other kinds of Kotlin DSLs, beyond builders, shall reconsider their use of extension receivers. Sometimes a Kotlin DSL
-is designed to inject a context into a block. For example, in current Kotlin code bases you might find declarations like
-
-```kotlin
-fun withVirtualTimeSource(block: TimeSource.() -> Unit) { ... }
-
-// Later in code
-withVirtualTimeSource {
-    val time = now() // provides virtual time in this block
-}
-```
-
-This is a good Kotlin style now, and there is no need to reconsider it for stable APIs. However, new Kotlin code shall
-be designed with context receivers in mind:
-
-```kotlin
-// GOOD STYLE: Better for newly designed code
-fun withVirtualTimeSource(block: context(TimeSource) () -> Unit) { ... }
-
-// Later in code
-withVirtualTimeSource {
-    val time = now() // Provides virtual time in this block
-}
-```
-
-This is not only stylistically better, as it clearly shows an intent to provide contextual information. 
-It is also better in a larger codebase, because the contextual lambda in `withVirtualTimeSource { ... }` does not
-change the meaning of `this` reference, for example:
-
-```kotlin
-class Subject { 
-    fun doSomething() {
-        withVirtualTimeSource {
-            val subject = this // `this` still refers to Subject instance
-        }
-    }
-}
-```
-
-### Designing context types
-
-You'd usually need to design new types from scratch to use them as context parameters due to the unique requirement on
-the naming of their members and extensions. They must be designed with context in mind. Use the same naming guidelines
-as if you are designing top-level declarations. A typical business-object would be usually inappropriate as a context receiver.
-
-Prefer interfaces to classes for context receivers. This would help you later on as your application grows — instead
-of carrying a number of different contexts in your top-level functions as in:
-
-```kotlin
-context(TimeSource, TransactionContext, LoggingContext, ...) // BAD: Too many separate contexts
-fun doSomeTopLevelOperation() { ... }
-```
-
-You'll have an option of combining multiple contexts into a single meaningfully named interface:
-
-```kotlin
-interface TopLevelContext : TimeSource, TransactionContext, LoggingContext, ...
-
-context(TopLevelContext) // GOOD: A combined context
-fun doSomeTopLevelOperation() { ... }
-```
-
-## Similar features in other languages
-
-Contextual abstractions exist in other languages.
-
-### Scala given instances and using clauses
-
-Scala 2 introduced the first implementation of contextual abstractions with "impicits": implicit objects, definitions,
-classes, and parameters. In Scala 3, "implicits" were redesigned and turned into given instances, using clauses and
-extension methods. Using clauses have a lot in common with context receivers.
-
-`using` always works together with some `given`. Given instance defines a value of a certain type, which the compiler can
-further use to generate an implicit argument for calls with a context parameter of this type.
-Meanwhile, a context parameter is defined with a `using` clause.
-
-```scala
-// Can be called only in the scope with the given of Ordering[Person] type
-def printPersons(s: Seq[Person])(using ord: Ordering[Person]) = ...
-```
-
-Context parameters are quite close to the context receivers we're describing in this proposal — they also consume a context
-from a caller scope. So the example above can be easily translated into Kotlin, preserving its semantics:
-
-```kotlin
-// Can be called only in the scope with the context receiver of Comparator<Person> type
-context(Comparator<Person>)
-fun printPersons(s: Sequence<Person>) = TODO()
-```
-
-### Algebraic effects and coeffects
-
-Algebraic effects is a mechanism that is being implemented in some research languages such as
-[Eff](https://www.eff-lang.org/) (with untyped effects) and [Koka](https://github.com/koka-lang/koka) (with typed effects)
-to model various effects that a function can have on its environment. For pure functional languages, they provide a
-unified abstraction for things like reading and writing state, throwing exceptions, doing input and output, etc.
-In essence, effects are similar to exceptions, but, unlike exceptions, which always abort the function's execution
-when thrown, effects can choose to continue execution. This is what makes it possible, for example, to use effects
-to model a computation that emits a string. For example, take a look at this example from Koka:
-
-```koka
-effect emit { // Somewhat similar to 'interface' declaration
-    fun emit(msg: string): () // '()' denotes 'Unit' in Koka
-}
-
-fun hello(): emit () { // Function has an effect of 'emit', returns `()`
-    emit("hello world!")
-}
-```
-
-The `hello` function must be called with the handler for the `emit` effect. For example, one can
-[print](https://koka-lang.github.io/koka/doc/std_core.html#println) emitted messages to the console:
-
-```koka
-fun helloToConsole() {
-    with handler { fun emit(msg) { println(msg) } }
-    hello()
-}
-```
-
-In languages with effects, the effects are modeled in a type system together with the return type. For example,
-the `hello` function in Koka has a type of `() -> emit ()` as it has no parameters, has an `emit` effect, and returns unit.
-Here the similarity of effects to checked (typed) exceptions is also apparent as checked exceptions represent a
-limited form of typed (checked) effects.
-
-Coeffects constitute a dual approach to modelling the same behavior as with effects. Instead of looking at effects
-that a function has, we can look at the context in which the function can be run (see
-[Thomas Petricek's work for details](http://tomasp.net/coeffects/)). Kotlin context receivers are a limited form of a typed
-(checked) coffect system. We can rewrite the declaration of the `hello` function with an `emit` effect to Kotlin as a
-function that requires an `Emit` context:
-
-```kotlin
-fun interface Emit {
-    fun emit(msg: String)
-}
-
-context(Emit)
-fun hello() {
-    emit("hello world!")
-}
-```
-
-Similarly to how effectful code can be only run with the handler for the corresponding effect, the contextual functions
-can only be run in the corresponding context:
-
-```kotlin
-fun helloToConsole() {
-    with(Emit { msg -> println(msg) }) {
-        hello()
-    }
-}
-```
-
-## Alternative approaches and design tradeoffs
-
-This section describes some alternatives that were considered during design.
-
-The main tradeoff we had to make with the proposed syntax is that in cases when the context is generic, then the use of the
-generic parameter happens before its declaration, e.g (from [Use cases](#use-cases) section):
-
-```kotlin
-context(Monoid<T>) // T is used
-fun <T> List<T>.sum(): T = ...
-//  ^^^ T is declared
-```
-
-We feel that it is not going to present a problem in idiomatic Kotlin code, since type parameters are usually a few and
-named with one uppercase letter, so there is not much need to have auto-completion for them in IDE.
-We can also make IDE smart enough to auto-complete the name in the declaration, if the long name is used in the context
-before being declared.
-
-### Alternative syntax options
-
-* Direct extensions of single-receiver syntax
-  ```kotlin
-  fun <T> (Monoid<T>, List<T>).sum(): T = ...
-  ```
-  Aside from complexity of finding nice syntax that does not interact negatively with other existing and potential
-  features of the language, this option does not make it possible to syntactically distinguish the object of the action
-  and the additional context of the action.
-
-* Extension block
-  ```kotlin
-  extension Monoid<T> {
-      fun List<T>.sum(): T = ...
-  }
-  ```
-  The nice part of it that is serves a double-duty of addressing the extension grouping request from
-  [KT-5670](https://youtrack.jetbrains.com/issue/KT-5670), but it is quite verbose for all the contextual use cases,
-  forcing an additional indentation level.
-
-* Context on the right-hand side of function declaration
-  ```kotlin
-  fun <T> List<T>.sum(): T context(Monoid<T>) = ...
-  ```
-  This placement would be consistent with Kotlin's `where` clause, but it is not consistent with receivers being specified
-  before the function name. Moreover, Kotlin has a syntactic tradition of matching declaration syntax and call-site syntax
-  and a context on a call-site is established before the function is invoked.
-
-### Alternative keywords
-
-We've considered a number of alternative keywords.
-
-* `with` (save as scope function to introduce receiver into scope)
-  * Note: reusing the same name will make it confusing in discussions
-* `using` (Scala name, but in Kotlin may clash with use)
-* `given` (will be confusing as Scala uses it for an opposite thing)
-* `implicit` (very different thing in Scala)
-* Meaning "inside of the additional receiver class or its context/scope"
-  * `within`
-  * `inside`
-  * Note: functions with additional receivers are not really inside, they don't see private
-* Meaning "in the context/scope of the receiver class"
-  * `incontext`
-  * `inscope`
-  * **`context` — our choice**
-  * `receiver`
-  * Highlights implicitness & the fact that they are required
-* Meaning "requiring/getting instance of the receiver class"
-  * `having`
-  * `receiving`
-  * `taking`
-  * `utilizing`
-  * `obtaining`
-  * `including`
-
-The choice of `context` was largely driven by its clear use in the prose, as it is quite natural to talk about
-"contextual functions" and other contextual abstractions, hence the keyword also fits well.
-
-### Parentheses vs angle brackets
-
-One of the big decisions around design was choosing between parentheses `context(Ctx)` and angle brackets `context<Ctx>`.
-Here is the summary of benefits we've found for these two options:
-
-* `context<Ctx>` syntax is consistent with how types are passed as arguments in Kotlin calls. 
-  If you have a `Type`, then you pass the corresponding type argument in angle brackets as in 
-  `foo<Type>()`, compare this to passing a class in `foo(Type::class)`. The same is true in annotations,
-  although annotations with type parameters are rarely used in Kotlin code due to their JVM interop limitations.
-  The notable exception is [Android Parcelize](https://developer.android.com/kotlin/parcelize) where you
-  could find annotations like`@TypeParceler<ExternalClass, ExternalClassParceler>()`. Angle brackets 
-  make this analogy of using a type stand out.
-* `context(Ctx)` syntax is consistent with Kotlin parameter declarations. When you declare a function
-  with a context receiver, as in `context(Ctx) fun foo(param: Param)`, you actually declare an additional 
-  anonymous parameter to a function of type `Ctx`. This analogy becomes especially notable when you 
-  consider that the functional type of this declaration, as explained in the [Functional types](#functional-types) section,  
-  is equivalent to `(Ctx, Param) -> Unit`. Parentheses make this analogy of declaring a parameter stand out. 
-
-> Another advantage of the angle brackets syntax is that it makes [Backwards compatibility](#backwards-compatibility) 
-> concerns go away completely, but they are so minor for parentheses anyway, that we did not pay much attention to
-> this difference.
-
-By themselves, these differences do not conclusively point to a choice of which syntactic option is better. 
-In the end, the decision was swayed in favor of parentheses, 
-because this syntax leaves more doors open for potential future extensions and refinements:
-
-* If we find compelling use-cases, we can naturally add support for named context receivers via 
-  `context(name: Ctx)` syntax similarly to named function parameters. 
-* If we ever find "type parameter use before declaration" problematic in practice, as explained in 
-  the beginning of the [Alternative approaches and design tradeoffs](#alternative-approaches-and-design-tradeoffs) section, 
-  the parentheses syntax lends itself to support type parameter introduction before its use
-  directly in the `context` parameter declaration as `context<T>(Monoid<T>)`.
-* If we ever find the need to support modifiers on context receivers, they will most likely be shared with 
-  parameters, due to parameter-like nature of context receivers, as in hypothetical `context(inline Ctx)`.
-
-### Context keyword ambiguities
-
-To avoid potential [Backwards compatibility](#backwards-compatibility) problems in the future with parentheses 
-we've considered making new syntax unambiguous everywhere (including function bodies) via additional syntax, 
-like `@context(Ctx)`,  `context:(Ctx)`,  `context@(Ctx)`, or `context.(Ctx)`. 
-None of the alternatives looked nice or natural.
-
-### Named context receivers
-
-We've looked at various ways to add names to the context receives as an alternative to the qualified `this` syntax
-for [Referencing specific context receiver](#referencing-specific-context-receiver). The leading syntactic option
-considered was `context(name: Type)` similarly to named function parameters.
-
-However, we did not find enough compelling use cases yet to support such naming, as context receivers are explicitly
-designed for something that should be brought into the context, as opposed to a declaration that should be explicitly
-referred to by name. Moreover, we do support disambiguation of multiple context receivers using a type-alias if needed.
-For cases where you need to bring a named thing into the context, there is a workaround.
-
-Consider an example where you want to bring some `callParameters: Map<String, String>` property into the context of
-certain functions in your backend application. If using `context(callParameters: Map<String, String>)` was supported,
-it would create a middle-ground concept that, on one hand, should not be brought into scope as a receiver, because
-the `Map` interface has lots of methods and is not designed to be used like that, but, on the other hand,
-should be implicitly passed down the call chain without syntactic overhead.
-
-Still, you want it named in the context and available for use. A proposed solution is to write the following interface:
-
-```kotlin
-interface CallScope {
-    val callParameters: Map<String, String>
-}
-```
-
-Now, all the relevant functions can declare `context(CallScope)` to get access to the `callParameters` property.
-
-### Multiple receivers with decorators
-
-We've looked at a way to combine contextual receivers with decorators into a single feature. Decorators is a potential
-future Kotlin feature designed to aid and reduce the amount of magic in typical aspect-oriented programming approaches.
-A decorator is a function that wraps another function's body with its code, for example:
-
-```kotlin
-// Declaring transactional decorator
-decorator fun transactional(block: Transaction.() -> Unit) {
-    beginTransation.use { tx ->
-        tx.block()
-    } // Closes transaction at the end    
-}
-
-@transactional // Use decorator to wrap function's body
-fun updateUserSession() {
-    val session = loadSession()
-    session.lastAccess = now()
-    storeSession(session)
-}
-```
-
-This way, the decorator also introduces an additional receiver into the function body and thus can serve as a syntax for
-functions with multiple receivers.
-
-However, semantics of declaration-only decorators (e.g. when `fun updateUserSession()` is a part of an interface) are
-harder to define consistently. A generic decorator, that would support bringing any context receiver into scope
-(e.g. `with` decorator function) will result in harder-to-read use code (something like
-`@with<Transaction> fun updateUserSession` was considered). Moreover, bringing additional receivers into scope via
-decorators does lend itself to clean separation from the regular extension receiver and to tweaks in the
-[Resolution algorithm](#resolution-algorithm) for those additional receivers, such as declaring multiple contexts
-without introducing order between them and making sure that context receivers do not otherwise affect the meaning of
-unqualified `this` expression.
-
-## Future work
-
-This section lists enhancements that are being prototyped, discussed, or otherwise being considered and are potentially
-possible in the future. Feel free to share your ideas in discussion [KEEP-259](https://github.com/Kotlin/KEEP/issues/259).
-
-### Reflection design
-
-Kotlin reflection will have to support the concept of context receivers and represent them in a similar way to dispatch
-and extension receivers. The detailed design for reflection is to be done later.
-
-### Contextual delegated properties
-
-The natural extension is to allow operator functions `getValue`, `setValue`, and `provideDelegate` of
-[Kotlin delegated properties convention](https://kotlinlang.org/docs/delegated-properties.html) to be contextual.
-That former two would allow, for example, using delegation to define transactional properties that can be accessed
-only in a context of transaction:
-
-```kotlin
-class TransactionalVariable<T> {
-    context(Transaction)
-    operator fun getValue(thisRef: Any?, property: KProperty<*>): T { ... }
-  
-    context(Transaction)
-    operator fun setValue(thisRef: Any?, property: KProperty<*>, value: T) { ... }
-}
-
-// Only available for get/set in a context of Transaction
-val userName by TransactionalVariable<String>()
-```
-
-### Local contextual functions and properties
-
-The current design excludes local functions and properties, because they add technical complications without bringing
-substantial benefits. However, supporting them would be a natural future extension. We'll have to design a plan for
-dealing with minor [Backwards compatibility](#backwards-compatibility) problems that would arise, some existing uses
-of the context name will have to be deprecated.
-
-### Callable references to contextual functions
-
-Support for callable references to contextual functions will need a resolution algorithm that is similar to how
-references to global functions are resolved, and unlike references to functions with a receiver:
-
-```kotlin
-context(LoggingContext)
-fun performSomeBusinessOperation(withParams: Params) { ... }
-
-::performSomeBusinessOperation // Will have type of context(LoggingContext) (Params) -> Unit
-```
-
-Currently, we don't have compelling use cases and plans to support special syntax for bound references to
-contextual functions (similarly to functions with a receiver). One can always use a lambda, e.g.
-
-```kotlin
-val op: (Params) -> Unit =
-    { params -> with(createLoggingContext()) { performSomeBusinessOperation(params) } }
-```
-
-### Removing context receiver from the scope with DslMarker
-
-Kotlin has a [`@DslMarker`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-dsl-marker/) annotation designed for DSLs.
-It is mainly designed to work with [Kotlin builders](#kotlin-builders) which should still be written using extension
-receivers as opposed to contextual receivers. However, it might be potentially useful to support `@DslMarker` annotations
-on contextual receivers for [Other Kotlin DSLs](#other-kotlin-dsls) if the corresponding use cases arise in the future.
-
-### Scope properties
-
-To call the contextual function, we need the required set of receivers to be brought in the caller scope, which can be
-done via scope functions `with`, `run`, or `apply`. However:
-
-* They add an extra pair of curly braces increasing the number of nested scopes and indentation levels.
-* They can be used only inside the function scope, while we might want to add a receiver in a class or even file scope.
-
-We consider the future introduction of **scope properties** — a lighter-weight approach to bring a context receiver into
-a scope with the regular property declaration syntax using `with` as a new keyword.
-
-```kotlin
-class Service {
-    with val serviceContext = createServiceContext() // Introduce the scope property with the service context
-
-    fun doSomething() {
-        // serviceContext is a context receiver inside the scope of the class, need not be named explicitly
-    }
-}
-```
-
-It is possible to gradually turn `with` into a hard keyword to support even more concise syntax for bringing
-annonymous receivers into the scope in a class:
-
-```kotlin
-class Service {
-    with createServiceContext() // Introduce anonymous scope property
-}
-```
-
-And, potentially, the same for the local scope 
-(expanding on [Algebraic effects and coeffects](#algebraic-effects-and-coeffects) example):
-
-```kotlin
-fun helloToConsole() {
-    with Emit { msg -> println(msg) }
-    hello()
-}
-```
-
-The detailed design for scope properties is to be presented later.
-
-### Contextual classes and contextual constructors
-
-> We included contextual classes and contextual constructors in the [prototype](#prototype) implemented in Kotlin 1.6.20-M1.
-
-Contextual classes and contextual constructors are yet another natural future extension of this proposal.
-They can be used to require some context to be present for instantiating the class, which has a bunch of use cases.
-
-```kotlin
-context(ServiceContext)
-class Service {
-    fun doSomething() {
-        // declarations from ServiceContext are available here
-    }
-}
-```
-
-With the [scope properties](#scope-properties) feature in mind, the above declaration will get desugared to:
-
-```kotlin
-class Service
-     // Constructor is contextual, needs ServiceContext when it is being invoked
-     context(ServiceContext) 
-     constructor() {} 
-
-     with this@ServiceContext // capture constructor's param into a scope property
-
-     fun doSomething() {
-         // declarations from ServiceContext are available here
-     }
-}
-```
-
-### Future decorators
-
-While we've decided to not rely on decorators for the core support of multiple receivers as explained in the
-[Multiple receivers with decorators](#multiple-receivers-with-decorators) section, the very concept of decorators is
-a useful one with its own use cases. Moreover, the concept of context receiver and the corresponding changes to the resolution
-rules to account for them is an important building block for decorators in the future.
-
-It is important for readability of code written in the Kotlin language to be clear on the meaning of unqualified `this`.
-Consider the example decorated function declaration:
-
-```kotlin
-@transactional // Use decorator to wrap function's body
-fun updateUserSession() { ... }
-```
-
-If `updateUserSession` is a top-level function, it should not have any `this` reference. If it is a member function, then
-`this` inside the function shall refer to an instance of its container class. A decorator, such as `@transaction`, even
-if it adds some declarations to the scope of the function's body, should not be empowered to change the meaning of `this`
-inside of it. The concept of context receiver is such a mechanism.
-
-### Unified context properties
-
-Frameworks, libraries, and applications sometimes need to pass various ad hoc local properties throughout the function
-call-chains. When a property is used by many functions in the call-chain, then it makes sense to define a dedicated
-context interface and explicitly declare all affected functions as contextual. For example, if most functions in our
-application need and use some kind of global configuration property, then we can declare the corresponding interface
-and mark all the functions in our app with `context(ConfigurationScope)`.
-
-```kotlin
-interface ConfigurationScope {
-    val configuration: Configuration
-}
-```
-
-The situation is different when an application uses lots of properties like that, but each function typically uses none or
-a few. Examples include authentication information, distributed call tracing, styling properties, etc. 
-
-If we model each property as a separate context interface, then the `context(...)` declarations will quickly get
-out of hand. Moreover, it becomes hard to add a new property somewhere deep down the call-chain, as the corresponding
-context needs to be passed through the whole call-stack. Another solution is to create an "uber context", which combines
-all the contextual properties any piece of the code might need, but this might be impossible in a big modular application,
-as specific properties can be local to a module or even local to a few functions in a larger module.
-
-A popular modular solution to pass such context properties is to use
-[ThreadLocal](https://docs.oracle.com/javase/8/docs/api/java/lang/ThreadLocal.html) variables. However, thread-locals
-are bound to a thread, so any framework whose execution context spans multiple threads must introduce its own solution,
-like [CoroutineContext](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/-coroutine-context/) in Kotlin coroutines,
-[CompositionLocal](https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal) in Jetpack Compose,
-[Context](https://projectreactor.io/docs/core/release/api/reactor/util/context/Context.html) in Project Reactor, etc.
-This is challenging for any code that uses several such frameworks together as it is not trivial to ensure preservation
-of the context properties when execution spans multiple frameworks. It can also get verbose in the frameworks themselves,
-as this context has to be manually passed through the framework code.
-
-If we focus on Kotlin-specific frameworks, then we see that each of them has a framework-specific mechanism to pass
-the context around:
-
-* [CompositionLocal](https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal) variables
-  are passed down the call-chain only via `@Composable` functions.
-* [CoroutineContext](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/-coroutine-context/) elements
-  are passed down the call-chain only via `suspend` functions.
-
-When you call a regular function, the context is lost. When you call a suspending function from a composable function,
-for example, then the context is lost, too. However, there are use cases where it is convenient to have a unified
-`ThreadLocal`-like approach to context properties that can be passed though different types of functions.
-
-A potential future solution is to declare a unified context properties framework in the Kotlin standard library, so that,
-first and foremost, it can be used with regular functions, for example:
-
-```kotlin
-val contextUser = contextProperty<User?>(null)
-
-context(PropertiesScope) // Can access context properties
-fun authenticate() {
-    val currentUser = contextUser.current // Retrieve from context
-    // ...
-}
-```
-
-Also, `suspend` and `@Composable` functions can be retrofitted to work as if they are declared with
-`context(PropertiesScope)` modifier and so will pass a set of current context properties via their calls,
-ensuring interoperability of the corresponding mechanisms.
-                               
-## Open issues and concerns
-
-This section lists known issues with this proposal that should be mitigated or accepted and weighed against
-the benefits this proposal brings.
-
-### Context receivers abuse and scope pollution
-
-Kotlin code may suffer from proliferation of implicit receivers in code. In the worst case, all implicit receivers 
-have to be checked to resolve the call during compilation. With many implicit receivers in scope human readers
-might also find it hard to figure it out where the declaration that code is using comes from. 
-
-```kotlin
-class AClass { // this: AClass 
-    fun Extension.doSomething() { // this: Extension
-       dsl1 { // this: Builder1
-           dsl2 { // this: Builder2
-               foo() // where is this function declared? 
-           }
-       }    
-    }    
-}
-```
-
-Currently, a single pair of nested curly braces `{...}`, being it a class, function, or a lambda, may add at 
-most one implicit receiver into scope. This naturally limits proliferation of implicit receivers. You can have at
-most as many implicit receivers in scope as the nesting level of your code.
-
-Introducing context receivers makes it possible to add multiple implicit receivers into scope per one nesting level,
-removing this natural limitation. If abused, this will make compilation slow (by having to scan move implicit receivers)
-and understanding code harder.
-
-The [contexts and coding style](#contexts-and-coding-style) section gives some naming rules and other advice
-designed to mitigate potential abuse of context receivers.
-
-### Methods from Any in top-level functions
-
-Counterintuitively, the following code will compile in this design:
-
-```kotlin
-context(LoggingContext)
-fun weirdToString(): String = toString() // OK
-```
-
-However, the following code will not compile (due to resolution ambiguity):
-
-```kotlin
-context(LoggingContext, Transaction)
-fun weirdToString(): String = toString() // ERROR
-```
-                                                              
-This is an effect of treating context receivers more or less like all other implicit receivers in Kotlin, 
-but bundling them into a single group in the [Resolution algorithm](#resolution-algorithm).
-
-All the methods defined on the [`Any`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/) type 
-(like `toString`, `equals`, `hashCode`) are available on any Kotlin class and 
-thus are also available in any function with a receiver, for example:
-
-```kotlin
-fun LoggingContext.weirdToString(): String = toString() // also OK
-```
-
-Context receivers do not create an entirely new problem here, but make an existing problem more pronounced. 
-One can find legal use cases for `Any` methods on an extension receiver, but we don't know any
-sensible use cases with context receivers, so their availability is an unwanted side effect for top-level 
-contextual functions. 
-
-# Prototype
-
-The first prototype of context receivers is available in Kotlin 1.6.20-M1 under the `-Xcontext-receivers` compiler option.
-Note that the implementation is experimental and IDE support is minimal. 
-Feel free to report any issues you face in [YouTrack](https://kotl.in/issue).
+Redirect to [KEEP-0259-context-receivers.md](KEEP-0259-context-receivers.md)
diff --git a/proposals/experimental.md b/proposals/experimental.md
deleted file mode 100644
index 1a2660409..000000000
--- a/proposals/experimental.md
+++ /dev/null
@@ -1 +0,0 @@
-Discussion is moved to [this file](opt-in.md)
\ No newline at end of file
diff --git a/proposals/scripting-support.md b/proposals/scripting-support.md
index 7903582e6..b1ccdc315 100644
--- a/proposals/scripting-support.md
+++ b/proposals/scripting-support.md
@@ -1,895 +1 @@
-
-# Kotlin Scripting support
-
-*Replaces [Script Definition Template](https://github.com/Kotlin/KEEP/blob/master/proposals/script-definition-template.md)
-proposal.*
-
-## Feedback
-
-Discussion of this proposal is held in [this issue](https://github.com/Kotlin/KEEP/issues/75)
-
-## Motivation
-
-- Define Kotlin scripting and its applications
-- Describe intended use cases for the Kotlin scripting
-- Define scripting support that is: 
-  - applicable to all Kotlin platforms
-  - provides sufficient control of interpretation and execution of scripts
-  - simple enough to configure and customize
-  - provides usable default components and configurations for the typical use cases    
-- Provide basic examples of the scripting usage and implementation
-- Address the issues found during the public usage of the current scripting support 
-
-## Status of this document
-
-The document is still a draft, and few important parts are still missing, in particular:
-
-- REPL:
-  - API for REPL host configuration and embedding
-  - API for REPL plugins (maybe should be covered elsewhere):
-    - custom repl commands
-    - highlighting
-    - completion
-    - etc.
-- IDE plugins API for custom scripting support (besides discovery)
-
-## Table of contents
-
-- [Applications](#applications)
-- [Basic definitions](#basic-definitions)
-- [Use cases](#use-cases)
-  - [Embedded scripting](#embedded-scripting)
-  - [Standalone scripting](#standalone-scripting)
-  - [Project infrastructure scripting](#project-infrastructure-scripting)
-  - [Script-based DSL](#script-based-dsl)
-- [Proposal](#proposal)
-  - [Architecture](#architecture)
-  - [Script definition](#script-definition)
-  - [Script Compilation](#script-compilation)
-  - [Script Evaluation](#script-evaluation)
-  - [Standard hosts and discovery](#standard-hosts-and-discovery)
-  - [How to implement scripting support](#how-to-implement-scripting-support)
-  - [Implementation status](#implementation-status)
-  - [Examples](#examples)
-    - [kotlin-main-kts](#kotlin-main-kts)
-
-## Applications
-
-- Build scripts (Gradle/Kobalt)
-- Test scripts (Spek)
-- Command-line utilities
-- Routing scripts (ktor)
-- Type-safe configuration files (TeamCity)
-- In-process scripting and REPL for IDE
-- Consoles like IPython/Jupyter Notebook
-- Game scripting engines
-- ...
-
-## Basic definitions
-
-- **Script** - a text file written in Kotlin language but allowing top-level statements and expressions and having access 
-  to some implicit (not directly mentioned in the script text) properties, functions and objects, as if the whole script 
-  body is a body of an implicit function placed in some environment (see below)
-- **Scripting Host** - an application or a component which handles script execution   
-- **Scripting Host Environment** - a set of parameters that defines an environment for all scripting host services,
-  contains when relevant: project paths, jdk path, etc. It is passed on constructing the services     
-- **REPL snippet** - a group of script text lines, executed in a single REPL eval call
-- **Script compilation configuration** - a set of parameters configuring script compilation, such as dependencies,
-  external variables declarations, implicit import statements, etc. 
-- **Script evaluation configuration** - a set of parameters configuring script evaluation, such as external variables 
-  instances, actual script parameters, etc. 
-- **Script definition** - a set of parameters and configurations defining a script type   
-- **Compiled script** - a binary compiled code of the script, stored in memory or on disk, which could be loaded 
-  and instantiated by appropriate platform
-- **Dependency** - an external library or another project whose declarations are available for the script being compiled 
-  and evaluated
-- **Imported script** - another script whose declarations are available for the script being compiled and evaluated
-- **Configuration refinement** - the process of updating script compilation and evaluation configurations during 
-  compilation/evaluation with parameter specific to the particular script exemplar, e.g. depending on the script 
-  contents
-
-## Use cases
-
-### Embedded scripting
-
-The use case when a scripting host is embedded into user's application, e.g. specialized console like 
-IPython/Jupyter notebook, Spark shell, embedded game scripting, IDE and other application-level scripting. 
-
-#### Environment and customization
-
-In this case the script is most likely need to run in a specific execution environment, defined by the scripting host. 
-The default script compilation and evaluation configurations are defined by the scripting host as well. The host may 
-provide script authors with a possibility to customize some configuration parameters, e.g. to add dependencies or 
-specify additional compilation options, e.g. using annotations in the script text:
-
-```kt
-@file:DependsOn("maven:artifact:1.0", "imported.package.*")
-@file:Import("path/to/externalScript.kts")
-@file:CompilerOptions("-someCompilerOpt")
-```
-
-To implement this the compilation/evaluation pipeline should provide a callback mechanism to call a host-provided code 
-that could analyze script text directly or parsed annotations in order to update compilation and evaluation 
-configurations with parameters depending on the script contents or other dynamic factors.
-
-If the host need to support several script *types*, i.e. sets of compilation configurations and customization means, 
-there should be a way for the host to distinguish the scripts and select appropriate set of 
-compilation/configuration/evaluation services and properties. The host authors can implement the selection based on any 
-script property, but due to the difficulties in supporting file type distinction based on anything but filename 
-extension across platforms and IDEs, the default implementations should support only extension-based or file name based 
-selection.     
-
-*Note: It would be nice to provide an infrastructure (complete hosts or libraries) that support some typical mean for 
-each platform to resolve external libraries from online repositories (e.g. - maven for JVM) out of the box.*
-
-#### Typical usages
-
-In a simple case, the developer wants to implement a scripting host to control script execution and provide the required 
-environment. One may want to write something as simple as:
-```kt
-KotlinScriptingHost().eval(File("path/to/script.kts"))
-```
-or
-```kt
-KotlinScriptingHost().eval("println(\"Hello from script!\")")
-```
-and the script should be executed in the current environment with some reasonable default compilation and evaluation 
-settings. If things need to be configured explicitly, the code would look like:
-```kt
-val scriptingHost = KotlinScriptingHost(configurationParams...)
-scriptingHost.eval(File("path/to/script.kts"), compilationConfiguration, evaluationConfiguration)
-```
-This would also allow the developer to control the lifetime of the scripting host.
-
-In cases then there is more control needed for the compilation and evaluation process, the direct use of the script
-compiler and evaluator could be desirable:
-```kt
-val scriptCompiler = KotlinScriptCompiler(configurationParams...)
-val compiledScript = scriptCompiler.invoke(File("path/to/script.kts"), compilationConfiguration)
-val scriptEvaluator = KotlinScriptEvaluator(configurationParams...)
-val evaluationResult = scriptEvaluator.invoke(compiledScript, evaluationConfiguration)
-```
-In addition in this case the compiled script could be evaluated more than once.
-
-#### More control
-
-To be able to run scripts in a user controlled environment, the following information bits could be configured or 
-provided to the host: 
-- *Script Compiler* - the service that will compile scripts into a form accepted by the Evaluator
-- *Script Compilation Configuration* - set of properties defining the script compilation settings, including:
-  - *Script Base Class* - an interface (or prototype) of the script class, expected by the executor, so the compiler
-    should compile script into the appropriate class
-  - *Dependencies* - external libraries that could be used in the script
-  - *Default imports* - import statements implicitly added to any compiled script
-  - *Provided properties* - properties with types that is assumed visible in the script scope
-  - etc.
-- *Script Evaluator* - the service that will actually evaluate the compiled scripts in the required execution 
-  environment
-- *Evaluation configuration* - set of properties defining an environment for the evaluation, including:
-  - *Provided properties* - actual values of the provided properties from the compilation configuration
-  - etc. 
-  
-Some of these parameters could be wrapped into a *Script Definition* for easier identification of the script types
-by the hosts that may support handling of the several script types simultaneously. 
-  
-#### Caching
-
-Since calling Kotlin compiler could be quite a heavy operation in comparison with typical script execution, the caching
-of the compiled script should be supported by the compilation platform.
-
-#### Execution lifecycle
-
-The script is executed according to the following scheme:
-- compilation - the *Script Compiler* takes the script, its compilation configuration and 
-  provides a compiled class. Inside this process. If the compilation configuration defines refinement callbacks, they 
-  are called before or after parsing to update configuration with parameter depending on the script contents or other
-  dynamic data.
-- evaluation - the *Script Evaluator* takes the compiled script instantiates it if needed, and calls the appropriate 
-  method, passing arguments from the environment to it; this step could be repeated many times. If evaluation 
-  configuration defines refinement callbacks, they will be called before evaluation similarly to the compilation ones.
-  
-#### Processing in an IDE
-
-The IDE support for the scripts should be based on the same *Script definition*. Basically after recognizing the script
-*type* (see *Environment and customization* section above), the IDE extracts the *Compilation Configuration* and use its 
-parameters to implement highlighting, navigation and other features. The default implementation of Kotlin IDEA plugin
-should support the appropriate functionality, based on the standard set of configuration parameters.
-
-### Standalone scripting
-
-Standalone scripting applications include command-line utilities and a standalone Kotlin REPL.
-
-Standalone scripting is a variant of the embedded scripting with hosts provided with the Kotlin distribution or 
-3rd-party hosts.
-
-#### Hosts
-
-The standalone script could be executed e.g. using command line Kotlin compiler:
-
-```sh
-kotlinc -cp <classpath required by the script definition> -script myscript.kts
-```
-
-Or with the dedicated runner included into the distribution:
-
-```sh
-kotlin -cp <classpath required by the script definition> myscript.kts
-```
-
-To be able to use the Kotlin scripts in a Unix shell environment, the *shebang* (`#!`) syntax should be supported 
-at the beginning of the script:
-```sh
-#! /path/to/kotlin/script/runner -some -params
-```
-
-*Note: due to lack of clear specification, passing parameters in the shebang line could be 
-[problematic](https://stackoverflow.com/questions/4303128/how-to-use-multiple-arguments-with-a-shebang-i-e/4304187#4304187), 
-therefore alternative schemes of configuring scripts should be available.*
-
-#### Script customizations
-
-It should be possible to process custom scripts with the standard hosts, e.g. by supplying a custom script definition 
-in the command line, e.g.:
-```sh
-kotlin -script-templates="org.acme.MyScriptDef" -cp myScriptDefLib.jar myscript.myscr.kts
-```
-In this case the host loads specified definition class, and extract required definition from it and its annotations.
-
-Another possible mechanism is automatic discovery, simplifying usage:
-```sh
-kotlin -cp myScriptDefLib.jar myscript.myscr.kts
-```
-In this case the host analyses the classpath, discovers script definitions located there and then processes then as 
-before. Note that in this case it is should be recommended to use dedicated script extension (`myscr.kts`) in every 
-definition to minimize chances of clashes if several script definitions will appear in the classpath. And on top of
-that, some selection mechanism based on the file names and/or paths is needed, e.g. to cover cases like gradle's 
-`build.gradle.kts` and `setting.gradle.kts` that should be treated like different script types.
-
-#### Script parameters
-
-For the command line usage the support for script parameters is needed. The simplest form is to assume that the script
-has access to the `args: Array<String>` property/parameter. More advanced is to have a customization that supports a 
-declaration of the typed parameters in the script annotations e.g.:
-
-```kt
-@file:param("name", "String?") // note: stringified types are used for the cases not supported by class literals
-@file:param("num", Int::class)  
-@file:param("list", "List<String>") 
-
-// this script could be called with args "-name=abc -num=42 -list=a,b,c" 
-// and then in the body we can access parsed typed arguments
-
-println("${name ?: "<unknown>"} ${num/6}: ${list.map { it.toUpperCase() } }") 
-```
-
-#### IDE support
-
-Since in this use case scripts are not part of any project, support for such script should be configured in the IDE
-explicitly, either via a plugin or via the IDE settings.
-
-#### Standalone REPL
-
-Standalone REPL is invoked by a dedicated host the same way as for standalone script but accepts user's input as repl 
-snippets. It means that the declarations made in the previous snippets are accessible in the subsequent ones.  
-In this mode, all new scripting features should be accessible as well, including customization.
-
-### Project infrastructure scripting
-
-Applications: project-level REPL, build scripts, source generation scripts, etc.
- 
-Project infrastructure scripts are executed by some dedicated scripting host usually embedded into the project build 
-system. So it is a variant of the embedded scripting with the host and the IDE support integrated into build system 
-and/or IDE itself.
-
-#### IDE support
-
-From an IDE point of view, they are project-context dependent, but may not be part of the project sources. (In the same 
-sense as e.g. gradle build scripts source is not considered as a part of the project sources.) In this case the support
-in the IDE is possible only if the definitions are supplied to the IDE explicitly, similarly to standalone scripts,
-either via a plugin or via the IDE settings.
-
-#### Discovery
-
-The IDE needs to be able to extract scripts environment configurations from the project settings, if the scrips are 
-considered a part of the project sources, so the project's classpath could be used for discovery of the supported 
-scripts.
- 
-#### Project-level REPL
- 
-A REPL that has access to the project's compiled classes.
-
-### Script-based DSL
-
-Applications: test definition scripts (Spek), routing scripts (ktor), type safe config files, etc.
- 
-In these cases the scripts are considered parts of the kotlin project and are compiled to appropriate binary form by the 
-compiler, and then linked with the rest of the compilation results. They differ from the other project's sources by the 
-possibility to employ script semantic and configurability and therefore avoid some boilerplate and make the sources 
-look more DSL-like.
- 
-In this scenario, no dedicated scripting host is used, but the standard compiler is used during the regular compilation 
-according to configured script recognition logic (e.g. the script type discovery mechanism described above), and the 
-target application should implement its own logic for instantiating and calling the generated script classes.  
-Script compiler may also annotate generated classes and methods with user-specified annotations to integrate it with 
-existing execution logic. E.g. junit test scripts could be annotated accordingly.
-
-From an IDE point of view, these scripts are the part of the project but should be configured according to the 
-recognized script definition.
-
-## Proposal
-
-### Architecture
-
-#### Components
-
-The scripting support consists of the following components:
-- `ScriptCompiler` - interface for script compilation
-  - compilation: `(scriptSource, compilationConfiguration) -> compiledScript`
-  - predefined script compilers based on the kotlin platforms: /JVM, /JS, /Native
-  - custom/customized implementation possible
-  - compiled scripts caсhing belongs here
-  - should not keep the state of the script compilation, the required state for the subsequent compilations, e.g. in the 
-    REPL mode, is passed along with the compiled script
-- `ScriptEvaluator` - the component that receives compiled script instantiates it, and then evaluates it in a required 
-  environment, supplying any arguments that the script requires:
-  - evaluation: `(compiledScript, evaluationConfiguration) -> Any?`
-  - the `compiledScript` contains the final compilation configuration used
-  - the `evaluationConfiguration` the parameters describing the actual script evaluation configuration of the script
-  - predefined platform-specific evaluators available, but could be provided by the scripting host
-  - pseudo-evaluators that save compiled script into e.g. an executable jar should be provided as well
-- **IDE support** - Kotlin IDEA plugin should have support for scripting with script definition selection based on the 
-  file name extension, and also includes discovery. The exposed generic ide support that would allow to build rich 
-  script editing apps and REPLs is outside of the scope of this proposal and will be covered elsewhere.    
-  
-#### Data structures
-  
-- `ScriptSource` determines the way to access script for other components; it consists of:
-  - the script reference pointer: url
-  - an accessor to the script text  
-  Both components are optional but at least one is required for a regular script.  
-  The class implements source position and fragment referencing classes used e.g. in error reporting. 
-- `KotlinType` a wrapper around Kotlin types, used to decouple script definition and compilation/evaluation 
-  environments. It could be constructed either from reflected or from stringified type representation.
-- `ScriptCompilationConfiguration` - a heterogeneous container of parameters defining the script compilation
-- `ScriptEvaluationConfiguration` - a heterogeneous container of parameters defining the script evaluation 
-- `ScriptingHostConfiguration` - a heterogeneous container of host-specific parameters  
-
-### Script definition
- 
-Script Definition is a way to specify custom script. It is basically consists of a script base class annotated with 
-`KotlinScript` annotation. The arguments of the annotation define the script configuration parameters.  For example: 
-
-```kt
-@KotlinScript(
-    displayName = "My Script",
-    fileExtension = "myscr.kts",
-    compilationConfiguration = MyScriptCompilationConfiguration::class,
-    evaluationConfiguration = MyScriptEvaluationConfiguration::class
-)
-abstract class MyScript(project: Project, val name: String) {
-    fun helper1() { ... } 
-    
-    [@ScriptBody]
-    [suspend] abstract fun <scriptBody>(params...): MyReturnType
-}
-
-object MyScriptCompilationConfiguration : ScriptCompilationConfiguration({
-    defaultImports("java.io.*")
-    providedProperties(prop1 to Int::class, prop2 to String::class)
-})
-
-object MyScriptEvaluationConfiguration : ScriptEvaluationConfiguration({
-    providedProperties(prop1 to 42, prop2 to "foo")
-})
-```
-
-*Where:*
-- any valid method name could be used in place of `<scriptBody>` 
-- `@ScriptBody` annotation marks the method the script body will be compiled into. In the absence of the explicit 
-  annotation, if the configuration requires compilation into a method, the SAM notation will be used, otherwise
-  the script will be generated into the target class constructor.
-- `interface` or `open class` could be used in place of the `abstract class`
--  *(see also possible compilation configuration properties below)*
-
-The annotations have reasonable defaults, so in the minimal case it is enough to mark the class only with the 
-`@KoltinScript` without parameters. But it is recommended to give a dedicated file name extension for every script 
-type to minimize chances for clashes in case of multiple definitions in one context.
-The file name extension could be declared in the compilation configuration as well, but it is highly recommended
-to define it in the annotation instead, since it will speed up the discovery process significantly.
-
-### Script Compilation
-
-#### Script Compiler
-
-Script compiler implements the following interface:
-```kt
-interface ScriptCompiler {
-
-    /**
-     * Compiles the [script] according to the [scriptCompilationConfiguration]
-     * @param script the interface to the script source code
-     * @param scriptCompilationConfiguration the script compilation configuration properties
-     * @return result wrapper, if successful - with compiled script
-     */
-    suspend operator fun invoke(
-        script: SourceCode,
-        scriptCompilationConfiguration: ScriptCompilationConfiguration
-    ): ResultWithDiagnostics<CompiledScript<*>>
-}
-```
-where:
-```kt
-interface CompiledScript<out ScriptBase : Any> {
-
-    /**
-     * The compilation configuration used for script compilation
-     */
-    val compilationConfiguration: ScriptCompilationConfiguration
-
-    /**
-     * The function that loads compiled script class
-     * @param scriptEvaluationConfiguration the script evaluation configuration properties
-     * @return result wrapper, if successful - with loaded KClass
-     */
-    suspend fun getClass(scriptEvaluationConfiguration: ScriptEvaluationConfiguration?): ResultWithDiagnostics<KClass<*>>
-
-    /**
-     * The name and the type of the script's result field, if any
-     */
-    val resultField: Pair<String, KotlinType>?
-}
-
-```
-The compilers for the supported platforms are supplied by default scripting infrastructure.
-  
-#### Script Dynamic Compilation Configuration
-
-The script compilation could be configured dynamically by specifying configuration refining callbacks in the compilation
-configuration. The callback should be written according to the following signature: 
-```kt
-typealias RefineScriptCompilationConfigurationHandler =
-            (ScriptConfigurationRefinementContext) -> ResultWithDiagnostics<ScriptCompilationConfiguration>
-```
-where:
-```kt
-class ScriptConfigurationRefinementContext(
-    val script: SourceCode,
-    val compilationConfiguration: ScriptCompilationConfiguration,
-    val collectedData: ScriptCollectedData? = null
-)
-```
-and `ScriptCollectedData` is a heterogeneous container of properties with the appropriate data collected during parsing.
-
-See the following section for the parameters that declare such callbacks.
-
-#### Compilation Configuration Properties
-
-The following properties are recognized by the compiler:
-- `baseClass` - target script superclass as well as a source for the script target method signature, constructor
-  parameters and annotations, default - `Any`.
-- `sourceFragments` - script fragments compile - allows to compile script partially
-- `scriptBodyTarget` - defines whether script body will be compiled into resulting class constructor or to a 
-  method body. In the latter case, there should be either single abstract method defined in the script base class, or
-  single appropriate method should be annotated with the `ScriptBody` annotation
-- `implicitReceivers` - a list of script types that is assumed to be implicit receivers for the script body, as
-  if the script is wrapped into `with` expressions, in the order from outer to inner scope, i.e.:  
-  ```kt
-  with(receiver0) {
-      ...
-      with(receiverN) {
-          <script body>
-      }
-  }
-  ```
-- `providedProperties` - a map (name -> type) of external variables visible for the script
-- `defaultImports` - a list of import statements implicitly added to the script
-- `restrictions` - a list of allow/deny rules containing qualified identifier wildcards, which are applied after
-  resolving any identifier used in the script to determine whether a particular identifier should be accessible for 
-  the script. This allows creating hosts with script functionality restrictions
-- `importedScripts` - a list of scripts definitions from which should be available for the compiled script
-- `dependencies` - a list of external libraries or modules available for the script
-- `copyAnnotationsFrom` - an external class those annotations should be copied to the generated target class; if not
-  specified, the annotations are copied from the base class (except for known scripting annotations)
-- `compilerOptions` - a list of additional compiler options that should be passed to compiler on script compilation
-- `resultField` - the name of the generated script class field to assign the script results to, empty means disabled, 
-  default - `$$result`
-- `refineConfigurationBeforeParsing` - a configuration refining callback that should be called before parsing is
-  started
-- `refineConfigurationOnAnnotations` - a list of script file-level annotations and configuration refining callback,
-  if the specified annotations are found in the parsed script, the callback is called to get an updated configuration. 
-- `refineConfigurationOnSections` - a list of top-level "sections" - function calls with single lambda parameter, e.g.  
-  ```kt
-  plugins {
-      ...
-  }
-  ```  
-  and the callback that should be called if specified sections are found in the parsed script
-  
-Additional properties are possible for particular platforms and compiler implementations.
-
-#### Script class
-
-In case of compiling into constructor, the script compiled into the following class
-
-```kt
-@CopiedAnnotation0(...)
-...
-@CopiedAnnotationN(...)
-class Script(
-    baseClassArguments..., 
-    receiver0: ReceiverType0, ..., receiverN: ReceiverTypeN,
-    val providedProperty0: ProvidedPropertyType0, ..., val providedPropertyN: ProvidedPropertyTypeN
-): ScriptBaseClass(baseClassArguments...) {
-    
-    val val1: V1 by initOnce // for all vals/vars defined in the script body
-    
-    fun fn1(...): R1 {} // for all funcs defined in the script body
-    
-    class Cl1(...) {} // for all classes/objects defined in the script body
-    
-    val $$result: ResultType
-    
-    init {
-        with(receiver0) {
-            ...
-            with(receiverN) {
-                <script body>
-                $$result = <last expression>
-            }
-        }
-    }
-}
-```
-
-In case of compiling into a method, the internal script properties are not exposed from the class:
-
-```kt
-@CopiedAnnotation0(...)
-...
-@CopiedAnnotationN(...)
-class Script(
-    baseClassArguments..., 
-    receiver0: ReceiverType0, ..., receiverN: ReceiverTypeN,
-    val providedProperty0: ProvidedPropertyType0, ..., val providedPropertyN: ProvidedPropertyTypeN
-): ScriptBaseClass(baseClassArguments...) {
-    
-    [suspend] fun <scriptBody>(lambdaParams...): ReturnType {
-        with(receiver0) {
-            ...
-            with(receiverN) {
-                <script body>
-            }
-        }
-    }}
-```
- 
-
-The actual name of the `<scriptBody>` method is defined by the script base class.
-
-The `implicitReceivers` may also contain compiled external scripts objects (from the `importedScripts` property).
-
-*Note: The `with (implicitReceivers)` wrapping is needed in all methods and initializers defined in the class.*
-
-### Script Evaluation
-
-#### Script Evaluator
-
-The script evaluator is an optional service (since the scripting host may choose to instantiate and execute compiled
-scripts manually) for instantiating and running compiled scripts. The default evaluators for supported platforms 
-are provided by the scripting infrastructure. It should implement the following interface:
-```kt
-interface ScriptEvaluator {
-    suspend operator fun invoke(
-        compiledScript: CompiledScript<*>,
-        scriptEvaluationConfiguration: ScriptEvaluationConfiguration?
-    ): ResultWithDiagnostics<EvaluationResult>
-}
-```
-
-#### Evaluation properties
-
-The following properties could be recognized by the evaluator, when passed in the `scriptEvaluationConfiguration` 
-parameter:
-- `implicitReceivers` - a list of actual implicit receivers objects, corresponding to the `implicitReceivers`
-  parameter in the compilation configuration
-- `providedProperties` - a map (name -> value) of the actual external variables visible to the script, corresponding to
-  the `providedProperties` parameter in the compilation configuration
-- `constructorArgs` - a list of constructor parameters corresponding to the script base class constructor, that should 
-  be passed to the script constructor
-- `runArgs` - a list of arguments to the script body method, if the `scriptBodyTarget` is set to the compiling script
-  into the method
-- `scriptsInstancesSharing` - boolean property defining the way of dealing with duplicates among imported scripts - if
-  true - the imported scripts instances are kept in a container and shared among all use sites in the import hierarchy.
-  (the helper `enableScriptsInstancesSharing()` provides another way of turning it on) 
-- `refineConfigurationBeforeEvaluate` - a configuration refining callback that should be called before evaluation is
-  started
-  
-It is possible to define and pass additional properties to a user-defined evaluator.    
-
-#### Scripting host configuration 
-
-These properties are defined by the scripting host and contain general parameters needed for all scripting services.
-In particular, it is assumed that `ScriptCompilationConfigurator` and `ScriptEvaluater` implementations are instantiated
-by passing the environment property bag to the appropriate constructors.  
-The following parameters are defined:
-- `configurationDependencies` - a list of dependencies required for script base class and services (configurator and
-  evaluator), but not necessarily for scripts themselves (see below)
-- `getScriptingClass` - an interface to an implementation-specific "class loader" for types specified in the 
-  configurations
-- `getEvaluationContext` - optional user-supplied function that can provide data to the evaluation configuration 
-  refinement functions 
-  
-### Standard hosts and discovery
-
-For standard JVM compiler, the command line parameter could be used to specify a script definition class name, and 
-then regular compilation classpath will be used for dependencies.
-
-Additionally, the automatic discovery of the templates marked by `@KotlinScript` annotation could be used with 
-libraries that do not have plugins able to provide an extension. This could, for example, be used for test frameworks.  
-In this case, the compiler scans all jars in the classpath for the discovery files - files in the folder 
-`META-INF/kotlin/script/templates/` those names correspond to fully qualified names of the annotated script base 
-classes. *(Note: the files' contents are not used, only the name)*. When it reads the annotations attached to these 
-classes and lazily constructs actual script definitions from them.  
-
-*(Note: the process is optimized in a way that if the file name extension could be extracted from the annotations alone,
-the actual definition is not loaded until we will actually start to compile a script with the appropriate extension. 
-This practically eliminates the overhead of script definitions discovery for projects that are not using scripts.)*
-
-### How to implement scripting support
-     
-To implement scripting support on the JVM one should do the following
-
-- Implement script definition library/module
-   - define custom script compilation configuration class, inherit it from `ScriptCompilationConfiguration` and pass
-     configuration lambda to the constructor of the latter
-   - define custom script evaluation configuration class, inherit it from `ScriptEvaluationConfiguration` and pass
-     configuration lambda to the constructor of the latter
-   - define script base class with the `@KotlinScript` and pass at least file name extension and the configuration 
-     classes to it
-   - optionally add a discovery file named after FQN of the base class to the `META-INF/kotlin/script/templates/` in 
-     the target jar 
-
-If discovery file is added to the resulting jar, and this jar is added to the compilation classapth, it becomes possible 
-to use custom script with the default hosts (e.g. Kotlin command-line compiler) and Kotlin IDEA plugin out of the box.   
-
-*(Note for usage with Gradle: the discovery process is not turned on by default in the Kotlin gradle plugin, to enable
-script definitions discovery in particular dependencies, they should be added to the `kotlinScriptDef` (or 
-`testKotlinScriptDef`, etc.) configuration)*
-
-Optionally the custom host and Idea support could be implemented:
-
-- Implement the scripting host with the following functionality:
-   - collect host configuration properties required for the services
-   - instantiate compiler and evaluator
-   - create basic host e.g. using platform-specific basic implementation   
-   - in case of custom implementation, on each eval:
-     - call compiler
-     - call evaluator
-      
-- Implement IDE support via the appropriate extension
-   - implement a class with `ScriptDefinitionsProvider` that returns appropriate definition class name and classpath
-     needed to load it. 
-   - use `org.jetbrains.kotlin.scriptDefinitionsProvider` extension point to register the provider class in IntelliJ
-   - in the script compilation configuration created as described above, add `ide` section with the following properties:
-     - `acceptedLocations` - the list of possible project locations where the script of this type will be recognized
-       (see. `ScriptAcceptedLocation` enum class for the possible values)
-     - `dependenciesSources` script source dependencies pointing to the jars with source code    
-
-### Implementation status
-
-The experimental implementation of the described scripting infrastructure on the JVM platform is a part of Kotlin 
-starting from the 1.3.0 release. The following API and helper libraries are generally needed for the implementation:
-- `kotlin-scripting-common` - API, interfaces, data structures and properties
-- `kotlin-scripting-jvm` - JVM-specific properties and default implementations
-- `kotlin-scripting-jvm-host` - JVM-specific host helpers
-
-The basic examples could be found in the `libraries/samples/scripting` folder in the Kotlin source code repository.
-
-The implementation is functional for many use cases, but there are many gaps, in particular:
-- the following compilation configuration properties are not supported yet:
-  - `sourceFragments` - scripts are only compiled as a whole for a moment; accordingly - the next point:
-  - `refineConfigurationOnSections` - is not implemented
-  - `scriptBodyTarget` - the generation into method body is not yet supported, so this parameter is ignored
-  - `restrictions` - not implemented yet
-  - `copyAnnotationsFrom` - is not implemented yet, the annotations are copied from the base class
-- some properties are required by the current implementation are not part of this proposal, because they exist only 
-  due to some implementation issues, and could soon disappear or change significantly, for example:
-  - `getScriptingClass` in the environment - is used for kotlin types instantiation; currently the instance of
-    `JvmGetScriptingClass` should be always used
-
-The standard host functionality including discovery is implemented in the command-line compiler, gradle plugin and IDEA
-plugin. But the following limitations are known:
-  - if the script definition module is in the same project as the usage part, the module (and in particular - base 
-    class) should be compiled to class files in order to be recognized by the discovery mechanism
-  - the script compilation in maven project is not supported yet
-  - the mechanisms for managing script definitions and resolving clashes are not implemented
-  - additional configuration is needed to enable script definitions discovery in a gradle build (see note in the 
-    [How to implement scripting support](#how-to-implement-scripting-support) section)
-    
-In general the scripting support is in the experimental stage, so we cannot guarantee stability of the interfaces and 
-implementations.
-
-### Examples
-
-#### kotlin-main-kts
- 
-The `kotlin-main-kts` artifact contains a script definition and a minimal maven artifacts resolver in a single jar.
-It allows to:
-- create and use the simple utility scripts that may depend on the external libraries;
-- extract the common functionality into “imported” scripts.
-
-It could be used as an example as an advanced script definition or together with standard or custom hosts - as an
-actual scripting tool. It implements JSR-223 host and therefore could be used via the `javax.script` API.
-
-To extend scripts with functionality from 3rd-party libraries and to organize scripts structure, the `kotlin-main-kts`
-implements support of the following file-level annotations:
-- `@DependsOn` allows specifying library dependencies for the script. Either a direct path to the file or jar, or 
-   maven coordinates are accepted as arguments.
-- `@Repository` adds the maven repository for resolving dependencies. If none are specified explicitly, the maven central 
-  repository is used.
-- `@Import` allows importing another script into a given one. All the actions specified in the imported script
-  run before all the actions specified in the given script and all the properties, functions and classes defined
-  in the imported scripts become visible for the given script.
-
-The artifact is distributed along with kotlin command line compiler package and published in Maven
-Central as `org.jetbrains.kotlin:kotlin-main-kts`.
-
-##### Usage
-
-###### Example scripts
-
-common.main.kts:
-```kt
-val greeting = "Hello, World!"
-```
-
-sample.main.kts:
-```kt
-@file:Repository("https://jcenter.bintray.com")
-@file:DependsOn("org.jetbrains.kotlinx:kotlinx-html-jvm:0.6.11")
-@file:Import("common.main.kts")
-
-import kotlinx.html.*
-import kotlinx.html.stream.*
-
-print(createHTML().html {
-    body {
-        h1 { +greeting }
-    }
-})
-```
-
-###### Running from command-line compiler (script definition discovery)
-
-```sh
-kotlinc -cp <path/to/kotlin-main-kts.jar> -script sample.main.kts
-```
-
-###### Simple host: eval function
-
-```kt
-fun evalFile(scriptFile: File): ResultWithDiagnostics<EvaluationResult> {
-
-    val compilationConfiguration = createJvmCompilationConfigurationFromTemplate<MainKtsScript>()
-    val evaluationConfiguration = createJvmEvaluationConfigurationFromTemplate<MainKtsScript>()
-
-    return BasicJvmScriptingHost().eval(scriptFile.toScriptSource(), compilationConfiguration, evaluationConfiguration)
-}
-
-evalFile(File("sample.main.kts")
-```
-
-###### Using JSR-223 (`javax.script`) API
-
-```kt
-val engine = ScriptEngineManager().getEngineByExtension("main.kts")!!
-engine.eval("""
-@file:DependsOn("junit:junit:4.11")
-
-org.junit.Assert.assertTrue(true)
-
-println("Hello, World!")
-""")
-```
-##### Implementation 
-
-The complete source code could be found in the `libraries/tools/kotlin-main-kts` folder in the Kotlin source 
-code repository. Here only partial sources are given to illustrate the main implementation points.
-
-###### Script base class
-
-```kt
-@KotlinScript(
-    fileExtension = "main.kts",
-    compilationConfiguration = MainKtsScriptDefinition::class,
-    evaluationConfiguration = MainKtsEvaluationConfiguration::class
-)
-abstract class MainKtsScript(val args: Array<String>)
-```
-
-###### Script compilation configuration properties
-
-```kt
-object MainKtsScriptDefinition : ScriptCompilationConfiguration(
-    {
-        defaultImports(DependsOn::class, Repository::class, Import::class)
-        jvm {
-            dependenciesFromClassContext( // extract dependencies from the host environment
-                MainKtsScriptDefinition::class, // use this class classloader for dependencies search
-                "kotlin-main-kts", "kotlin-stdlib", "kotlin-reflect" // search these libraries in it and use then as a script compilation classpath
-            )
-        }
-        refineConfiguration {
-            onAnnotations(
-                DependsOn::class, Repository::class, Import::class, // if these annotations are found on script parsing 
-                handler = MainKtsConfigurator() // call this handler to refine configuration parameters
-            )
-        }
-        ide {
-            acceptedLocations(ScriptAcceptedLocation.Everywhere) // these scripts are recognized everywhere in the project structure
-        }
-        jsr223 {
-            importAllBindings(true) // when used as a JSR-223 host, import engine bindings as kotlin properties
-        }
-    })
-```
-
-###### Script evaluation configuration properties
-
-```kt
-object MainKtsEvaluationConfiguration : ScriptEvaluationConfiguration(
-    {
-        scriptsInstancesSharing(true) // if a script is imported multiple times in the import hierarchy, use a single copy
-
-        refineConfigurationBeforeEvaluate( // before evaluation, call this handler to refine configuration properties
-            ::configureProvidedPropertiesFromJsr223Context
-        )
-    }
-)
-```
-
-###### Compilation configuration refinement handler
-
-```kt
-class MainKtsConfigurator : RefineScriptCompilationConfigurationHandler {
-    private val resolver = FilesAndIvyResolver()
-
-    override operator fun invoke(context: ScriptConfigurationRefinementContext): ResultWithDiagnostics<ScriptCompilationConfiguration> =
-        
-        val annotations = context.collectedData?.get(ScriptCollectedData.foundAnnotations)?.takeIf { it.isNotEmpty() }
-            ?: return context.compilationConfiguration.asSuccess()
-
-        // collect imported scripts paths from  Import annotations 
-        val scriptBaseDir = (context.script as? FileBasedScriptSource)?.file?.parentFile
-        val importedSources = annotations.flatMap {
-            (it as? Import)?.paths?.map { sourceName ->
-                FileScriptSource(scriptBaseDir?.resolve(sourceName) ?: File(sourceName))
-            } ?: emptyList()
-        }
-
-        // pass resolving annotations to resolver
-        val resolvedClassPath = try {
-            val scriptContents = object : ScriptContents {
-                override val annotations: Iterable<Annotation> = annotations.filter { it is DependsOn || it is Repository }
-                override val file: File? = null
-                override val text: CharSequence? = null
-            }
-            resolver.resolve(scriptContents, emptyMap(), {}, null).get()?.classpath?.toList()
-            // TODO: add diagnostics
-        } catch (e: Throwable) {
-            return ResultWithDiagnostics.Failure(*diagnostics.toTypedArray(), e.asDiagnostics(path = context.script.locationId))
-        }
-
-        // return updated configuration with resolved dependencies and imported scripts
-        return ScriptCompilationConfiguration(context.compilationConfiguration) {
-            if (resolvedClassPath != null) updateClasspath(resolvedClassPath)
-            if (importedSources.isNotEmpty()) importScripts.append(importedSources)
-        }.asSuccess()
-    }
-}
-```
-
-###### The discovery file (resources)
-  
-`META-INF/kotlin/script/templates/org.jetbrains.kotlin.mainKts.MainKtsScript.classname`
-
+Redirect to [KEEP-0075-scripting-support.md](KEEP-0075-scripting-support.md)
diff --git a/proposals/stdlib/window-sliding.md b/proposals/stdlib/KEEP-0011-window-sliding.md
similarity index 100%
rename from proposals/stdlib/window-sliding.md
rename to proposals/stdlib/KEEP-0011-window-sliding.md
diff --git a/proposals/stdlib/map-copying.md b/proposals/stdlib/KEEP-0013-map-copying.md
similarity index 100%
rename from proposals/stdlib/map-copying.md
rename to proposals/stdlib/KEEP-0013-map-copying.md
diff --git a/proposals/stdlib/string-to-number.md b/proposals/stdlib/KEEP-0019-string-to-number.md
similarity index 100%
rename from proposals/stdlib/string-to-number.md
rename to proposals/stdlib/KEEP-0019-string-to-number.md
diff --git a/proposals/stdlib/occurrences-of.md b/proposals/stdlib/KEEP-0020-occurrences-of.md
similarity index 100%
rename from proposals/stdlib/occurrences-of.md
rename to proposals/stdlib/KEEP-0020-occurrences-of.md
diff --git a/proposals/stdlib/group-and-fold.md b/proposals/stdlib/KEEP-0023-group-and-fold.md
similarity index 100%
rename from proposals/stdlib/group-and-fold.md
rename to proposals/stdlib/KEEP-0023-group-and-fold.md
diff --git a/proposals/stdlib/on-each.md b/proposals/stdlib/KEEP-0047-on-each.md
similarity index 100%
rename from proposals/stdlib/on-each.md
rename to proposals/stdlib/KEEP-0047-on-each.md
diff --git a/proposals/stdlib/bignumber-operations.md b/proposals/stdlib/KEEP-0049-bignumber-operations.md
similarity index 100%
rename from proposals/stdlib/bignumber-operations.md
rename to proposals/stdlib/KEEP-0049-bignumber-operations.md
diff --git a/proposals/stdlib/abstract-collections.md b/proposals/stdlib/KEEP-0053-abstract-collections.md
similarity index 100%
rename from proposals/stdlib/abstract-collections.md
rename to proposals/stdlib/KEEP-0053-abstract-collections.md
diff --git a/proposals/stdlib/KEEP-0127-result.md b/proposals/stdlib/KEEP-0127-result.md
new file mode 100644
index 000000000..625f4bd40
--- /dev/null
+++ b/proposals/stdlib/KEEP-0127-result.md
@@ -0,0 +1,752 @@
+# Encapsulate successful or failed function execution 
+
+* **Type**: Standard Library API proposal
+* **Author**: Roman Elizarov
+* **Contributors**: Andrey Breslav, Ilya Gorbunov
+* **Status**: Implemented in Kotlin 1.3
+* **Revisions**: Updated in Kotlin 1.5, see [revision history](#revision-history).  
+* **Related issues**: [KT-18608](https://youtrack.jetbrains.com/issue/KT-18608) 
+* **Original discussion**: [KEEP-127](https://github.com/Kotlin/KEEP/issues/127)
+
+## Summary
+
+Kotlin provides exceptions that are used to represent an arbitrary failure of a function and include 
+ability to attach additional information pertaining to this failure. Exceptions are sequential in nature and work 
+great in any kind of sequential code, including code for a single coroutine or in other case where one piece 
+of work in being sequentially decomposed. Exceptions ensure that the first failure in a sequentially performed work
+stops further progress and is propagated up to the caller. However, sequential nature of exceptions
+complicates their use in cases where some kind of parallel decomposition of work is needed or multiple
+failures need to be retained for later processing. 
+
+We'd like to introduce a type in the Kotlin standard library that is effectively a discriminated union between successful
+and failed outcome of execution of Kotlin function &mdash; `Success T | Failure Throwable`, 
+where `Success T` represents a successful result of some type `T` 
+and `Failure Throwable` represents a failure with any `Throwable` exception. 
+For the purpose of efficiency, we would model it as a generic `@JvmInline value class Result<T>` 
+in the standard library. 
+
+**NOTE: In Kotlin 1.3 till 1.5 this `Result` could not be used directly as a return type of Kotlin functions.
+This restriction was lifted in Kotlin 1.5.
+See [limitations](#limitations-legacy) section for details.
+See also [style and exceptions](#error-handling-style-and-exceptions) and 
+[use cases](#use-cases) below on how `Result` is designed to be used.** 
+
+## Use cases
+
+This section lists motivating use-cases.
+
+### Continuation and similar callbacks
+
+The primary driver for inclusion of this class into the Standard Library is `Continuation<T>` callback interface
+that should get invoked on the successful or failed execution of an asynchronous operation.
+We'd like to be able to have only a single function with "success or failure" union type as its parameter:
+
+```kotlin
+interface Continuation<in T> {
+    fun resumeWith(result: Result<T>)
+}
+```  
+
+### Asynchronous parallel decomposition
+
+Another example here is parallel execution of multiple asynchronous operations that must capture 
+successful or failed execution of each individual piece to analyze and reach decision on the outcome of a 
+larger piece of work:
+
+```kotlin
+val deferreds: List<Deferred<T>> = List(n) { 
+    async { 
+        /* Do something that produces T or fails */ 
+    } 
+}
+val outcomes1: List<T> = deferreds.map { it.await() } // BAD -- crash on the first (by index) failure
+val outcomes2: List<T> = deferreds.awaitAll() // BAD -- crash on the earliest (by time) failure 
+val outcomes3: List<Result<T>> = deferreds.map { runCatching { it.await() } } // !!! <= THIS IS THE ONE WE WANT  
+```     
+
+### Functional bulk manipulation of failures
+
+Kotlin encourages writing code in a functional style. It works well as long as business-specific failures are
+represented with nullable types or sealed class hierarchies, while other kinds of failures 
+(that are represented by exceptions) do not require any special local handling. However, when interfacing with
+Java-style APIs that rely heavily on exceptions or otherwise having a need to somehow process exceptions locally
+(as opposed to propagating them up the call stack), we see a clear lack of primitives in the Kotlin standard library.
+
+Consider writing a function `readFiles` that receives a list of files, reads all of them, and returns a 
+list of results. We are given the following function to read single file contents:
+
+```kotlin
+fun readFileData(file: File): Data
+```
+
+This reading function throws exception if file is not found or parsing of a file had somehow failed. Normally that would
+be fine, and the first failure of this kind would terminate the whole program with a stacktrace and explanatory message. 
+However, for `readFiles` we'd explicitly like to be able to continue after the failure to collect and report all failures.
+Moreover, we'd like to be able to have a functional implementation of `readFiles` like this:
+
+```kotlin
+fun readFilesCatching(files: List<File>): List<Result<Data>> =
+    files.map { 
+        runCatching { 
+            readFileData(it)
+        }
+    }
+```
+
+> This function is named `readFileCatching` to make it explicit to the caller that all encountered failures
+were _caught_ and encapsulated in `Result` and it is caller responsibility to process these failures.
+
+Now, consider making some transformation of `readFilesCatching` results that we'd like to express functionally, 
+while preserving accumulated failures:
+
+```kotlin                                                     
+readFilesCatching(files).map { result: Result<Data> -> // type explicitly written here for clarity
+    result.map { it.doSomething() } // Operates on Success case, while preserving Failure
+}
+```
+
+If `doSomething`, in turn, can potentially fail and we are interested in keeping this failure per each individual
+file, then we can write it using `mapCatching` instead of `map`:
+
+```kotlin
+readFilesCatching(files).map { result: Result<Data> -> 
+    result.mapCatching { it.doSomething() }
+}
+```
+
+### Functional error handling
+
+In mostly functional code `try { ... } catch(e: Throwable) { ... }` construct looks
+out of style. For example, consider this piece of code that uses [RxKotlin](https://github.com/ReactiveX/RxKotlin) 
+for asynchronous processing.
+It invokes `doSomethingAsync` that returns 
+[`Single`](http://reactivex.io/RxJava/javadoc/io/reactivex/Single.html) and processes potential error in a functional style:
+
+```kotlin
+doSomethingAsync()
+    .subscribe(
+        { processData(it) },
+        { showErrorDialog(it) }
+    )
+```
+
+> Note, that the above code is written in a style that is very different from direct programming style. `doSomethingAsync()`
+that returns `Single` does not actually do anything until `subscribe` is invoked 
+(its result is typically _cold_). This distinction is not important for the purposes of this section.
+We are interested here in a visual fact that error and result handling are chained to the initial invocation.
+
+Working with function that returns Java's [`CompletableFuture`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)
+is visually similar:
+
+```kotlin
+doSomethingAsync()
+    .whenComplete { data, exception ->
+        if (exception != null) 
+            showErrorDialog(exception)
+        else 
+            processData(data)
+    }
+```
+
+> It is closer to direct style, since this `doSomethingAsync` invocation actually starts performing operation, but 
+we also see that ultimate processing of success or failure is performed via chaining.  
+
+Now, if `doSomethingSync` is a synchronous function, then handling its success or failure looks quite visually different,
+which is problematic for the code that mixes both approaches:
+
+```kotlin
+try { 
+    val data = doSomethingSync()
+    processData(data) 
+} catch(e: Throwable) { 
+    showErrorDialog(e) 
+}
+```  
+
+> Also note, that the code with `try/catch` has different semantics, since it also catches exceptions that could have
+been thrown by `processData`. Preserving functional-style error-handling semantics using `try/catch` 
+is quite non-trivial (see [Error handling alternative](#error-handling-alternative) section).
+
+Instead, we'd like to be able to write the same code in a more functional way:
+
+```kotlin
+runCatching { doSomethingSync() }
+    .onFailure { showErrorDialog(it) }
+    .onSuccess { processData(it) }
+```
+
+## Alternatives
+
+There is a number of community-supported libraries that provide this kind of success or failure union type, 
+but we cannot use any of them for the `Continuation` callback interface that is defined in the Standard Library.
+
+### Continuation alternative
+ 
+Alternative signatures for the `Continuation` interface are listed below.
+
+**Two methods** as in current experimental version of coroutines:
+
+```kotlin
+interface Continuation<in T> {
+    fun resume(value: T)
+    fun resumeWithException(exception: Throwable)
+}
+```  
+
+This solution was tried in the experimental version of Kotlin coroutines and the following problems were identified:
+
+* All implementations have to implement both methods and there is no easy shortcut to provide a builder with
+  a lambda like `Continuation { ... body ... }`.
+* Some implementations need to capture "success or failure" in their state and pass on captured success or failure
+  to another delegate continuation at a later time.
+* Some implementations have a common piece of logic that should be executed on both success and failure 
+  with minor differences for successful and failed cases. These implementations have to immediately forward both
+  `resume` and `resumeWithException` to some internal function like `doResume`, thus increasing stack size and still
+  forcing implementor to figure out a way to represent both success and failure in one method.    
+
+**One method with two parameters**:
+
+```kotlin
+interface Continuation<in T> {
+    fun resume(value: T?, exception: Throwable?)
+}
+```  
+
+The downside here is that both parameters here are nullable and there is no larger type-safety nor 
+a clear indication of intent to have only one of them set.
+
+**One method with Any? parameter**:
+
+```kotlin
+interface Continuation<in T> {
+    fun resume(result: Any?) // result: T | Failure(Throwable)
+}
+```  
+
+This solution completely lacks any type-safety on Kotlin side.
+
+### Error handling alternative
+
+Let's see what it takes to rewrite the code with functional-style error handling without resorting to 3rd party libraries.
+
+**Non-nullable value type**:
+
+If the result of `doSomethingSync` is non-nullable, then we can write somewhat concise code:
+
+```kotlin
+val data: Data? = try { 
+        doSomethingSync() 
+    } catch(e: Throwable) { 
+        showErrorDialog(e)
+        null 
+    }
+if (data != null)    
+    processData(data) 
+```
+
+**Nullable value type**:
+
+If the result of `doSomethingSync` is nullable, then one possible alternative is shown below: 
+
+```kotlin
+var data: Data? = null
+val success = try { 
+        data = doSomethingSync()
+        true 
+    } catch(e: Throwable) { 
+        showErrorDialog(e)
+        false 
+    }
+if (success)    
+    processData(data) 
+```
+
+## API details
+
+The following snippet gives summary of all the public APIs:
+
+```kotlin
+@JvmInline value class Result<out T> /* internal constructor */ {
+    val isSuccess: Boolean
+    val isFailure: Boolean
+    fun getOrNull(): T?
+    fun exceptionOrNull(): Throwable?
+    
+    companion object {
+        fun <T> success(value: T): Result<T>
+        fun <T> failure(exception: Throwable): Result<T>
+    }
+}
+
+inline fun <R> runCatching(block: () -> R): Result<R>
+inline fun <T, R> T.runCatching(block: T.() -> R): Result<R>
+
+fun <T> Result<T>.getOrThrow(): T
+fun <R, T : R> Result<T>.getOrDefault(defaultValue: R): R
+
+inline fun <R, T : R> Result<T>.getOrElse(onFailure: (exception: Throwable) -> R): R
+inline fun <R, T> Result<T>.fold(onSuccess: (value: T) -> R, onFailure: (exception: Throwable) -> R): R
+
+inline fun <R, T> Result<T>.map(transform: (value: T) -> R): Result<R>
+inline fun <R, T: R> Result<T>.recover(transform: (exception: Throwable) -> R): Result<R>
+
+inline fun <R, T> Result<T>.mapCatching(transform: (value: T) -> R): Result<R>
+inline fun <R, T: R> Result<T>.recoverCatching(transform: (exception: Throwable) -> R): Result<R>
+
+inline fun <T> Result<T>.onSuccess(action: (value: T) -> Unit): Result<T>
+inline fun <T> Result<T>.onFailure(action: (exception: Throwable) -> Unit): Result<T>
+```
+
+The functions have self-explanatory consistent names that follow established tradition in the Kotlin Standard library
+and establish the following additional conventions:
+
+* Functions that can throw previously suppressed (captured) exception are named 
+  with explicit `OrThrow` suffix like `getOrThrow`.
+* Functions that capture thrown exception and encapsulate it into `Result` instance are named 
+  with explicit `Catching` suffix like `runCatching` and `mapCatching`.
+* A traditional `map` transformation function that works on successful cases 
+  is augmented with a `recover` function that similarly transforms exceptional cases. 
+  A failure inside either `map` or `recover` transform aborts operation like a traditional function, 
+  but `mapCatching` and `recoverCatching` encapsulate failure in transform into the resulting `Result`.
+* Functions to query the case are naturally named `isSuccess` and `isFailure`. 
+* Functions that act on the success or failure cases are named `onSuccess` and `onFailure` and return their receiver
+  unchanged for further chaining according to tradition established by `onEach` extension from the Standard Library.  
+  
+String representation of the `Result` value (`toString`) is either `Success(v)` or `Failure(x)` where `v` and `x` are 
+the string representations of the corresponding value and exception. `equals` and `hashCode` are implemented 
+naturally for the result type, comparing the corresponding values or exceptions.
+
+## Dependencies
+
+This library depends on 
+[`@JvmInline value class`](https://github.com/kotlin/KEEP/blob/master/proposals/inline-classes.md) 
+language feature for its efficient implementation. 
+
+## Limitations (legacy)
+
+In versions before Kotlin 1.5 `Result<T>` cannot be used as a direct result type of Kotlin functions, properties of 
+`Result` type are also restricted:
+
+```kotlin
+fun findUserByName(name: String): Result<User> // ERROR: 'kotlin.Result' cannot be used as a return type 
+fun foo(): Result<List<Int>> // ERROR 
+fun foo(): Result<Int>? // ERROR
+var foo: Result<Int> // ERROR
+```
+
+However, functions that use `Result` type in generic containers or receive result as a parameter type 
+were allowed:
+
+```kotlin
+fun findIntResults(): List<Result<Int>> // Ok
+fun receiveIntResult(result: Result<Int>) // Ok
+```
+
+Functions that declare generic result types may, in fact, return values of `Result` type when the
+`Result` type is substituted in place of their generic type parameters:
+
+```kotlin
+private val first: Result<Int> = findIntResults().first() // Ok, even though `first` is of type Result<Int>
+```
+
+Private and local properties of `Result`  type were allowed as long as they did not have custom getters:
+
+```kotlin
+private var foo: Result<Int> // Ok
+```
+
+The use of Kotlin null-safety operators `?.`, `?:` and `!!` was not allowed on both nullable and non-null `Result` types:
+
+```kotlin
+val r: Result<String?> = runCatching { readLine() }
+println(r!!) // ERROR
+```
+ 
+The rationale behind these limitations was that future versions of Kotlin might wish to expand and/or change semantics
+of functions that return `Result` type and null-safety operators may change their semantics when used
+on values of `Result` type. In order to avoid breaking existing code in the future releases of Kotlin and leave door open 
+for those changes, the corresponding uses produced an error. Exceptions to this rule were made for carefully-reviewed
+declarations in the standard library that are part of the `Result` type API itself. 
+
+**UPDATE**: These limitations are lifted since Kotlin 1.5.  
+
+See [Future advancements](#future-advancements) for details on specific plans on updates on them.
+
+## Binary contract and implementation details
+
+`Result<T>` is implemented by an `@JvmInline value class` and is optimized for a successful case. Success is stored as
+a value of type `T` directly, without additional boxing, while failure exception is wrapped into an internal 
+`Result.Failure` class that is not exposed through binary interface and may be changed later. 
+
+`Result` class has the following internal published APIs that 
+represent its binary interface on JVM in addition to its public [API](#api-details):
+
+```kotlin
+@JvmInline value class Result<out T> @PublishedApi internal constructor(
+    @PublishedApi internal val value: Any? // internal value -- either T or Failure
+) : Serializable
+
+@PublishedApi internal fun createFailure(exception: Throwable): Any
+@PublishedApi internal fun Result<*>.throwOnFailure()
+```  
+
+## Error-handling style and exceptions
+
+The `Result` class is designed to capture generic failures of Kotlin functions for their latter processing and
+should be used in general-purpose API like futures, etc, that deal with invocation of Kotlin code blocks and
+must be able to represent both a successful and a failed result of execution. The `Result` class is not
+designed to represent domain-specific error conditions.
+
+In general, if some API requires its callers to handle failures locally (immediately around or next to the invocation), 
+then it should use nullable types, when these failures do not carry additional business meaning, 
+or domain-specific data types to represent its successful results and failures with any additional business-related
+data that is needed to process these failures.  
+
+Consider this hypothetical API design:
+
+```kotlin
+fun findUserByName(name: String): Result<User> // ERROR 
+```
+
+If the only kind of failure we might be interested in handling is the failure to find 
+the user with the given name, then the following signature shall be used:
+
+```kotlin
+fun findUserByName(name: String): User? // Ok
+```   
+   
+If there is a business need to distinguish different failures and process these different failures in distinct ways
+on each invocation site, then the following kind of signature shall be considered:
+
+```kotlin
+sealed class FindUserResult {
+    data class Found(val user: User) : FindUserResult()
+    data class NotFound(val name: String) : FindUserResult()
+    data class MalformedName(val name: String) : FindUserResult()
+    // other cases that need different business-specific handling code
+}
+
+fun findUserByName(name: String): FindUserResult
+```
+
+_Exceptions_ in Kotlin are designed for the failures that usually do not require local handling at each call site.
+This includes several broad areas &mdash; logic and programming errors like index bounds problems and various checks
+for internal invariants and preconditions, environment problems, out of memory conditions, etc. 
+These failures are usually non-recoverable (or are not supposed to be recovered from) and are handled in some 
+centralized way by logging or otherwise reporting them for troubleshooting, typically terminating application
+or, sometimes, attempting to restart or to reinitialize an application as a whole or just its failing subsystem.       
+This is where default exceptions behaviour to abort current operation and propagate it up the call stack comes in handy. 
+
+External environment problems like network or file input/output errors represent a corner case here. 
+It is cumbersome to require their local handling by the caller as it complicates sequential business 
+logic by obscuring it with code to handle IO errors, so it is idiomatic in Kotlin to use exceptions (like `IOException`) 
+for these. However, they are often handled at a more granular level than some global error-handling code. 
+These errors often require some specific user-interaction and can require domain-specific retry or recovery code.
+
+> Exceptions are also very expensive _to create_, but relatively cheap to _throw_, because they carry a lot of 
+additional metadata, like stack trace and message to aid in debugging. They are extremely valuable when this 
+metadata is written to the log for developers to aid in troubleshooting, but all that metadata is useless if
+exception is to be consumed by some business-logic to make some business-decision based simple on the presence of 
+exception. Use nullable types or domain-specific classes to represent failures that need specific handling.
+
+So, in case when `findUserByName` failure does not require local handling by the caller, then its failure 
+should be represented by exception and its signature should look like this:
+
+```kotlin
+fun findUserByName(name: String): User
+```
+
+> This signature is fine if we always sure that user shall be found, unless we have bugs, environment or IO issues.
+
+If invoker of this function wants to perform multiple operations and process their failures afterwards
+(without aborting on the first failure), it can always use `runCatching { findUserByName(name) }` 
+to make it explicit that a failure is being caught and
+encapsulated into `Result` instance. 
+
+## Similar API review
+
+Kotlin Standard Library provides rich collection of transformations for nullable types that are idiomatic in Kotlin
+to indicate failure when no additional information about the failure is needed. However, there is no build-in support
+for non-standard exception handling in the Standard Library -- exceptions always terminate operation and propagate to the caller.
+
+Other programming languages include a similar facility to represent a union of success and failure in their standard 
+library with the following names:
+
+* [`Try[T]`](https://www.scala-lang.org/api/current/scala/util/Try.html) in Scala is similar to the proposed `Result<T>`.
+* [`Result<T, E>`](https://doc.rust-lang.org/std/result/) in Rust (also parametrized by the type of error).
+* [`Exceptional e t`](https://wiki.haskell.org/Exception) in Haskell (also parametrized by the type of error).  
+* [`expected<E, T>`](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4015.pdf) in C++ (proposed, also parametrized by the type of error).
+
+Existing Kotlin libraries that provide similar functionality:
+
+* [`Try<T>`](https://arrow-kt.io/docs/datatypes/try/) from [Arrow](https://github.com/arrow-kt/arrow) library.
+* [`Result<T, E>`](https://github.com/kittinunf/Result) from @kittinunf. 
+
+> Note, that both of the libraries above promote "Railway Oriented Programming" 
+style with monads and their transformations, which heavily relies on functions returning `Try`, `Result`, etc.
+This programming style can be implemented and used in Kotlin via libraries as the above examples demonstrate.
+However, core Kotlin language and its Standard Library are designed around a _direct_ programming 
+[style](#error-handling-style-and-exceptions) in mind. 
+The general approach in Kotlin is that alternative programming styles
+should be provided as 3rd party libraries and DSLs. 
+
+For a more detailed comparison of Scala's `Try` and its Kotlin analogue in Arrow library with this `Result` class
+see [Appendix](#appendix-why-flatmap-is-missing). 
+
+## Placement
+
+This API shall be placed into the Kotlin Standard Library. Since the proposed API is fairly small and does not
+clearly belong to any larger group of APIs, it should be placed directly into `kotlin` package.  
+
+## Open issues
+
+This section lists open issues about this design.
+
+### Parameterization by the base error type
+
+Parameterizing this class by the type of exception like `Result<T, E>` is possible, but raises the
+following problems:
+    
+* It increases verboseness without providing improvement for any of the outlined [Use cases](#use-cases).
+* Kotlin currently lacks facility to specify default values for generic type parameters.
+* It leads to abuse in cases where a user-provided API-specific sealed class would work better.   
+
+It is possible to define a separate class like `ResultEx<T, E>` that is parametrized by 
+both successful type `T` and failed type `E` (that must extend `Throwable`)
+and then define `Result<T>` and a `typealias` to `ResultEx<T, Throwable>`.
+However, this creates its own problems:
+
+* Typealiases are quite verbosely rendered by IDE in signatures and there is no clear way on making them better.   
+* We cannot succinctly define `runCatching` function 
+  and other `Catching` functions to make them usable both with and without explicit caught type specification.
+  We'll have to have two different names for such a function: one for a function with an additional `E: Throwable` 
+  type parameter that must be specified and another one without it. Moreover, specifying `E` on call site requires 
+  specifying return type, too, since partial type parameter specification is not currently possible in Kotlin.  
+
+All in all, it does not seem that the costs outweigh whatever benefits it might bring.
+
+> Defining an even more general `Either<L, R>` type as a discriminated union between two arbitrary types 
+`L` and `R` and then using `typealias Result<T> = Either<Throwable, T>` raises similar problems with 
+an additional burden of designing functions for `Either` that would not needlessly pollute the namespace
+of functions applicable to `Result`. We don't have sufficient motivating use-cases for having
+`Either` in the Kotlin Standard Library beyond theoretical desire to base `Result` upon it. 
+
+### Result must be used
+
+Using `Result` as the return type of `Catching` functions poses a problem that it might accidentally get lost, 
+thus losing unhandled exception. 
+
+Consider this code from [Functional bulk manipulation of failures](#functional-bulk-manipulation-of-failures):
+
+```kotlin                                                     
+readFilesCatching(files).map { result ->
+    result.map { it.doSomething() } 
+}
+```
+
+If `doSomething` here throws an exception, then all exceptions that were returned in a list by `readFilesCatching` are lost.
+
+Some IDE inspections can be designed to detect these kinds of problems. 
+It is an open question how exactly they should
+work and and whether it is really a big problem after all.
+
+### Additional APIs for collections
+
+API for `Result` class is designed to be quite bare-bones.
+However, according to [Functional bulk manipulation of failures](#functional-bulk-manipulation-of-failures) use-case,
+one might occasionally encounter `List<Result<T>>` or another collection of `Result` instances. 
+It is open question whether we should provide additional extensions in the Standard Library to represent common
+operations on such collections and what those operations might be. 
+
+## Future advancements
+
+This section lists potential directions for future enhancement. None of them are worked out at the moment
+and all of them are purely tentative.
+
+### Representing as a sealed class
+
+Kotlin `@JvmInline value` classes cannot be currently used with `sealed class` construct. 
+If that is supported in the future, then we could change implementation of 
+`Result` without affecting its public APIs and binary interfaces in the following way:
+
+```kotlin
+@JvmInline sealed value class Result<T> {
+    @JvmInline class Success<T>(val value: T) : Result<T>()
+    class Failure<T>(val exception: Throwable) : Result<T>()
+}
+``` 
+
+> Notice, that only `Success` case is marked with `@JvmInline` annotation here. That is the case that should be
+represented without boxing. In general, if `@JvmInline sealed value` classes are allowed in the future,
+then Kotlin compiler could only support `@JvmInline` annotation on a set of subclasses with pairwise non-intersecting 
+types of their primary constructor properties. In particular, both `Success` and `Failure` cannot be `@JvmInline` 
+at the same time, since we would not be able to distinguish `Success(Exception(...))` from 
+`Failure(Exception(...))` at run time.
+
+These changes would make it possible to use `result is Success` and `result is Failure` expressions and get advantage of
+smart casts instead of `result.isSuccess` and `result.isFailure` that are currently provided and which do not work 
+with smart casts.
+
+### Parameterizing by the base error type
+
+If `Kotlin` adds some form of support for type parameter default values and partial type inference,
+then we can consider extending `Result` class with an additional type parameter `E: Throwable` that represents
+the base class for caught exceptions. For example, in input/output code there may be a desire to catch only 
+`IOException` and its subclasses, while aborting on any other exception using something like
+`runCatching<_, IOException> { code }` assuming that return type can be still inferred
+(potential partial type inference syntax here is used for illustration only).
+
+### Integration into the language
+
+Kotlin nullable types have extensive support in Kotlin via operators `?.`, `?:`, `!!`, and `T?` type constructor
+syntax. We can envision better integration of `Result` into the Kotlin language in the future.
+However, unlike nullable types, that are often used to represent _non signalling_ failure that does not cary
+additional information, `Result` instances also carry additional information and, in general, shall be
+always handled in some way. Making `Result` an integral part of the language also requires a 
+considerable effort on improving Kotlin type system to ensure proper handling of encapsulated exceptions.
+
+**UPDATE**: We have reached a decision of not following this road for a foreseeable future and will not pursue integration
+of any special constructions into the language that are tied to the `Result` type. As a part of the standard library 
+a `Result` type will stay narrowly-focused on the use-cases that are described at the beginning of this document, 
+abandoning ambitions to become any kind of universal error-handling primitive. We are working in other directions
+of making signalling error handling more pleasant to use in Kotlin. 
+The text below is left for historical reasons. 
+
+One potential direction is to allow  return value of `Result` type, 
+so that with parametrization by the base error type one can write:
+
+```kotlin
+fun findUserByName(name: String): Result<User, IOException>
+``` 
+
+This declaration would be conceptually equivalent to a Java function that is declared with `User` 
+result type and `throws IOException` annotation.
+However, unlike `throws` annotation in Java, `Result<User, IOException>` is going to 
+be considered a _return type_ of this function that explicitly declares exception that must be handled locally.
+There will be no silent propagation of that exception type up to the caller. The caller will be 
+required to handle it explicitly. When one writes:
+
+```kotlin
+val result = findUserByName(name)
+```  
+
+Then inferred type of `result` will be `Result<User, IOException>`. 
+Direct access to the `User` methods and extensions would not be possible,
+but all the `?.`, `?:`, and `!!` operators can be extended to work appropriately with `Result` type to 
+make the corresponding code fluent 
+in a similar way as it happens with nullable types today. Some additional operators might be required, too.
+
+Unlike checked exception in Java, these are going to be full-blown types, so they play nicely with collections
+(`List<Result<User, IOException>>` is going to be a valid type) 
+and all the higher-order functions in Kotlin will work properly with those types without the problems
+that made it impossible to properly integrate checked exceptions with Java generics. 
+
+Moreover, it can be very efficiently implemented on JVM in the return type position by actually throwing the corresponding
+exception inside and catching it outside, on the caller side, so no boxing will be required even for primitive
+results. "Rethrowing" exceptions with `!!` can be transparent in JVM bytecode in the same way as it
+happens in Java programs using exceptions.
+
+> **Update note**: This proves virtually impossible to implement correctly, as there would be no way to distinguish
+> a domain-specific error that needs to be represented in the `Result` type for handling it by the caller from the 
+> logic error in the code (a crash) that shall still be represented as exception to be handled in a centralized place
+> of the application for logging, etc.
+
+All in all, it could provide a safe replacement for checked exceptions on JVM and open a path to a better
+integration with JVM APIs that rely on checked exceptions. However, details of this interoperability will have to 
+be worked out as there are lots of problems down this path. We cannot just lift all Java functions with `throws` into
+Kotlin functions with the corresponding `Result` type not only because of backwards compatibility, but also due to the way checked 
+exceptions are (ab)used in the JVM ecosystem, so are more fine-grained control for interoperability will have to 
+be designed.   
+
+It is all beyond the scope of this KEEP.
+
+## Appendix: Why flatMap is missing
+
+You can skip this appendix is you are not familiar with Scala's or Arrow's `Try` monad that provides very 
+similar functionality to this `Result` class. 
+
+If you are familiar with `Try` monad, then you might ask why there is no `flatMap` 
+function on the `Result` class. This function could have been defined with the following signature:
+
+```kotlin
+inline fun <R, T> Result<T>.flatMap(transform: (T) -> Result<R>): Result<R>
+```  
+
+The usual reason to have `flatMap` is to avoid "nesting" of monadic types when combining multiple
+functions that return them, like in the following example:
+
+```kotlin
+runCatching { d.await() }.map { it.doSomethingCatching() } // : Result<Result<Data>> -- oops!
+``` 
+ 
+Functional code that uses `Try` monad gets quickly polluted
+with `flatMap` invocations. To make such code manageable, a functional programming language is usually extended 
+with monad comprehension syntax to hide those `flatMap` invocations.  
+
+Take a look at the following example code that
+uses monad comprehension over `Try` monad 
+(which is adapted from a guide 
+[here](https://danielwestheide.com/blog/2012/12/26/the-neophytes-guide-to-scala-part-6-error-handling-with-try.html)):
+ 
+```scala
+def getURLContent(url: String): Try[Iterator[String]] =
+  for {
+    url <- parseURL(url) // here parseURL returns Try[URL], encapsulates failure
+    connection <- Try(url.openConnection())
+    input <- Try(connection.getInputStream)
+    source = Source.fromInputStream(input)
+  } yield source.getLines()
+```
+
+Adapting functions used here to Kotlin style, one can write this code in Kotlin, 
+with the same semantics of aborting further progress on the first failure, in the following way:
+
+```kotlin
+fun getURLContent(url: String): List<String> {
+    val url = parseURL(url) // here parseURL returns URL, throws on failure
+    val connection = url.openConnection()
+    val input = connection.getInputStream()
+    val source = Source.fromInputStream(input)
+    return source.getLines()
+}
+```
+
+Notice, that monad comprehension over `Try` monad is basically built into the Kotlin language.
+That is how imperative control flow works in Kotlin out of the box and there is no need to emulate it
+via monad comprehensions. If callers of this function need an encapsulated failure,
+they can always use `runCatching { getURLContent(url) }` expression.
+
+However, the Kotlin is not exactly equivalent to the initial code with `Try`.
+Let us see what are the differences. The original `parseURL` have been returning an encapsulated exception
+and it could be making a _fine grained_ decision on which kinds of exceptions shall be encapsulated into the result
+and which kinds of exceptions shall be thrown. Rewritten code propagates any failure in `parseURL` up to the caller 
+without this fine grained distinction between different kinds of failures. There is also a subtle difference on
+the `fromInputStream` invocation. Original code would fail with exception if this invocation fails, while any failure
+in `openConnection` and `getInputStream` is encapsulated into the result of the function via `Try`. Rewritten code 
+does not make distinctions between different kinds of failures anymore.
+
+All in all, the differences can be summarized as follows. `Result` is a blunt tool designed to catch
+any failure in the function invocation for the processing later on.
+On the other hand, libraries like [Arrow](https://arrow-kt.io) provide utility classes like `Try` and the 
+corresponding extension functions that enable more fine-grained control. When a function is declared with `Try<T>`
+as its result type, it means that this function can make a fine-grained decision on which failures are encapsulated
+and which failures are thrown up the call stack.       
+
+If your code needs fine-grained exception handling policy, we'd recommend designing your code in such a way, that
+exceptions are not used at all for any kinds of locally-handled failures 
+(see section on [style](#error-handling-style-and-exceptions) for example code
+with nullable types and sealed data classes). In the context of this appendix, `parseURL` could return a nullable
+result (of type `URL?`) to indicate parsing failure or return its own purpose-designed sealed class that would provide 
+all the additional details about failure (like the exact failure position in input string) 
+if that is needed for some business function 
+(like setting cursor to the place of failure in the user interface).
+In cases when you need to distinguish between different kinds of failures and these approaches do not work for you, 
+you are welcome to write your own utility libraries or use libraries like [Arrow](https://arrow-kt.io) 
+that provide the corresponding utilities.    
+
+## Revision history
+
+* **Kotlin 1.5**
+  * Allow returning the `Result` type from functions.
+  * Allow Kotlin null-safety operators `?.`, `?:` and `!!` on both nullable and non-null `Result` types.
+  * Text updated to replace `inline class` with `@JvmInline value class`.
diff --git a/proposals/stdlib/random.md b/proposals/stdlib/KEEP-0131-random.md
similarity index 100%
rename from proposals/stdlib/random.md
rename to proposals/stdlib/KEEP-0131-random.md
diff --git a/proposals/stdlib/durations-and-time-measurement.md b/proposals/stdlib/KEEP-0190-durations-and-time-measurement.md
similarity index 100%
rename from proposals/stdlib/durations-and-time-measurement.md
rename to proposals/stdlib/KEEP-0190-durations-and-time-measurement.md
diff --git a/proposals/stdlib/runningFold-and-runningReduce.md b/proposals/stdlib/KEEP-0207-runningFold-and-runningReduce.md
similarity index 100%
rename from proposals/stdlib/runningFold-and-runningReduce.md
rename to proposals/stdlib/KEEP-0207-runningFold-and-runningReduce.md
diff --git a/proposals/stdlib/locale-agnostic-case-conversions.md b/proposals/stdlib/KEEP-0223-locale-agnostic-case-conversions.md
similarity index 100%
rename from proposals/stdlib/locale-agnostic-case-conversions.md
rename to proposals/stdlib/KEEP-0223-locale-agnostic-case-conversions.md
diff --git a/proposals/stdlib/char-int-conversions.md b/proposals/stdlib/KEEP-0227-char-int-conversions.md
similarity index 100%
rename from proposals/stdlib/char-int-conversions.md
rename to proposals/stdlib/KEEP-0227-char-int-conversions.md
diff --git a/proposals/stdlib/optional-extensions.md b/proposals/stdlib/KEEP-0321-optional-extensions.md
similarity index 100%
rename from proposals/stdlib/optional-extensions.md
rename to proposals/stdlib/KEEP-0321-optional-extensions.md
diff --git a/proposals/stdlib/result.md b/proposals/stdlib/result.md
index 625f4bd40..f6fb3a7bc 100644
--- a/proposals/stdlib/result.md
+++ b/proposals/stdlib/result.md
@@ -1,752 +1 @@
-# Encapsulate successful or failed function execution 
-
-* **Type**: Standard Library API proposal
-* **Author**: Roman Elizarov
-* **Contributors**: Andrey Breslav, Ilya Gorbunov
-* **Status**: Implemented in Kotlin 1.3
-* **Revisions**: Updated in Kotlin 1.5, see [revision history](#revision-history).  
-* **Related issues**: [KT-18608](https://youtrack.jetbrains.com/issue/KT-18608) 
-* **Original discussion**: [KEEP-127](https://github.com/Kotlin/KEEP/issues/127)
-
-## Summary
-
-Kotlin provides exceptions that are used to represent an arbitrary failure of a function and include 
-ability to attach additional information pertaining to this failure. Exceptions are sequential in nature and work 
-great in any kind of sequential code, including code for a single coroutine or in other case where one piece 
-of work in being sequentially decomposed. Exceptions ensure that the first failure in a sequentially performed work
-stops further progress and is propagated up to the caller. However, sequential nature of exceptions
-complicates their use in cases where some kind of parallel decomposition of work is needed or multiple
-failures need to be retained for later processing. 
-
-We'd like to introduce a type in the Kotlin standard library that is effectively a discriminated union between successful
-and failed outcome of execution of Kotlin function &mdash; `Success T | Failure Throwable`, 
-where `Success T` represents a successful result of some type `T` 
-and `Failure Throwable` represents a failure with any `Throwable` exception. 
-For the purpose of efficiency, we would model it as a generic `@JvmInline value class Result<T>` 
-in the standard library. 
-
-**NOTE: In Kotlin 1.3 till 1.5 this `Result` could not be used directly as a return type of Kotlin functions.
-This restriction was lifted in Kotlin 1.5.
-See [limitations](#limitations-legacy) section for details.
-See also [style and exceptions](#error-handling-style-and-exceptions) and 
-[use cases](#use-cases) below on how `Result` is designed to be used.** 
-
-## Use cases
-
-This section lists motivating use-cases.
-
-### Continuation and similar callbacks
-
-The primary driver for inclusion of this class into the Standard Library is `Continuation<T>` callback interface
-that should get invoked on the successful or failed execution of an asynchronous operation.
-We'd like to be able to have only a single function with "success or failure" union type as its parameter:
-
-```kotlin
-interface Continuation<in T> {
-    fun resumeWith(result: Result<T>)
-}
-```  
-
-### Asynchronous parallel decomposition
-
-Another example here is parallel execution of multiple asynchronous operations that must capture 
-successful or failed execution of each individual piece to analyze and reach decision on the outcome of a 
-larger piece of work:
-
-```kotlin
-val deferreds: List<Deferred<T>> = List(n) { 
-    async { 
-        /* Do something that produces T or fails */ 
-    } 
-}
-val outcomes1: List<T> = deferreds.map { it.await() } // BAD -- crash on the first (by index) failure
-val outcomes2: List<T> = deferreds.awaitAll() // BAD -- crash on the earliest (by time) failure 
-val outcomes3: List<Result<T>> = deferreds.map { runCatching { it.await() } } // !!! <= THIS IS THE ONE WE WANT  
-```     
-
-### Functional bulk manipulation of failures
-
-Kotlin encourages writing code in a functional style. It works well as long as business-specific failures are
-represented with nullable types or sealed class hierarchies, while other kinds of failures 
-(that are represented by exceptions) do not require any special local handling. However, when interfacing with
-Java-style APIs that rely heavily on exceptions or otherwise having a need to somehow process exceptions locally
-(as opposed to propagating them up the call stack), we see a clear lack of primitives in the Kotlin standard library.
-
-Consider writing a function `readFiles` that receives a list of files, reads all of them, and returns a 
-list of results. We are given the following function to read single file contents:
-
-```kotlin
-fun readFileData(file: File): Data
-```
-
-This reading function throws exception if file is not found or parsing of a file had somehow failed. Normally that would
-be fine, and the first failure of this kind would terminate the whole program with a stacktrace and explanatory message. 
-However, for `readFiles` we'd explicitly like to be able to continue after the failure to collect and report all failures.
-Moreover, we'd like to be able to have a functional implementation of `readFiles` like this:
-
-```kotlin
-fun readFilesCatching(files: List<File>): List<Result<Data>> =
-    files.map { 
-        runCatching { 
-            readFileData(it)
-        }
-    }
-```
-
-> This function is named `readFileCatching` to make it explicit to the caller that all encountered failures
-were _caught_ and encapsulated in `Result` and it is caller responsibility to process these failures.
-
-Now, consider making some transformation of `readFilesCatching` results that we'd like to express functionally, 
-while preserving accumulated failures:
-
-```kotlin                                                     
-readFilesCatching(files).map { result: Result<Data> -> // type explicitly written here for clarity
-    result.map { it.doSomething() } // Operates on Success case, while preserving Failure
-}
-```
-
-If `doSomething`, in turn, can potentially fail and we are interested in keeping this failure per each individual
-file, then we can write it using `mapCatching` instead of `map`:
-
-```kotlin
-readFilesCatching(files).map { result: Result<Data> -> 
-    result.mapCatching { it.doSomething() }
-}
-```
-
-### Functional error handling
-
-In mostly functional code `try { ... } catch(e: Throwable) { ... }` construct looks
-out of style. For example, consider this piece of code that uses [RxKotlin](https://github.com/ReactiveX/RxKotlin) 
-for asynchronous processing.
-It invokes `doSomethingAsync` that returns 
-[`Single`](http://reactivex.io/RxJava/javadoc/io/reactivex/Single.html) and processes potential error in a functional style:
-
-```kotlin
-doSomethingAsync()
-    .subscribe(
-        { processData(it) },
-        { showErrorDialog(it) }
-    )
-```
-
-> Note, that the above code is written in a style that is very different from direct programming style. `doSomethingAsync()`
-that returns `Single` does not actually do anything until `subscribe` is invoked 
-(its result is typically _cold_). This distinction is not important for the purposes of this section.
-We are interested here in a visual fact that error and result handling are chained to the initial invocation.
-
-Working with function that returns Java's [`CompletableFuture`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)
-is visually similar:
-
-```kotlin
-doSomethingAsync()
-    .whenComplete { data, exception ->
-        if (exception != null) 
-            showErrorDialog(exception)
-        else 
-            processData(data)
-    }
-```
-
-> It is closer to direct style, since this `doSomethingAsync` invocation actually starts performing operation, but 
-we also see that ultimate processing of success or failure is performed via chaining.  
-
-Now, if `doSomethingSync` is a synchronous function, then handling its success or failure looks quite visually different,
-which is problematic for the code that mixes both approaches:
-
-```kotlin
-try { 
-    val data = doSomethingSync()
-    processData(data) 
-} catch(e: Throwable) { 
-    showErrorDialog(e) 
-}
-```  
-
-> Also note, that the code with `try/catch` has different semantics, since it also catches exceptions that could have
-been thrown by `processData`. Preserving functional-style error-handling semantics using `try/catch` 
-is quite non-trivial (see [Error handling alternative](#error-handling-alternative) section).
-
-Instead, we'd like to be able to write the same code in a more functional way:
-
-```kotlin
-runCatching { doSomethingSync() }
-    .onFailure { showErrorDialog(it) }
-    .onSuccess { processData(it) }
-```
-
-## Alternatives
-
-There is a number of community-supported libraries that provide this kind of success or failure union type, 
-but we cannot use any of them for the `Continuation` callback interface that is defined in the Standard Library.
-
-### Continuation alternative
- 
-Alternative signatures for the `Continuation` interface are listed below.
-
-**Two methods** as in current experimental version of coroutines:
-
-```kotlin
-interface Continuation<in T> {
-    fun resume(value: T)
-    fun resumeWithException(exception: Throwable)
-}
-```  
-
-This solution was tried in the experimental version of Kotlin coroutines and the following problems were identified:
-
-* All implementations have to implement both methods and there is no easy shortcut to provide a builder with
-  a lambda like `Continuation { ... body ... }`.
-* Some implementations need to capture "success or failure" in their state and pass on captured success or failure
-  to another delegate continuation at a later time.
-* Some implementations have a common piece of logic that should be executed on both success and failure 
-  with minor differences for successful and failed cases. These implementations have to immediately forward both
-  `resume` and `resumeWithException` to some internal function like `doResume`, thus increasing stack size and still
-  forcing implementor to figure out a way to represent both success and failure in one method.    
-
-**One method with two parameters**:
-
-```kotlin
-interface Continuation<in T> {
-    fun resume(value: T?, exception: Throwable?)
-}
-```  
-
-The downside here is that both parameters here are nullable and there is no larger type-safety nor 
-a clear indication of intent to have only one of them set.
-
-**One method with Any? parameter**:
-
-```kotlin
-interface Continuation<in T> {
-    fun resume(result: Any?) // result: T | Failure(Throwable)
-}
-```  
-
-This solution completely lacks any type-safety on Kotlin side.
-
-### Error handling alternative
-
-Let's see what it takes to rewrite the code with functional-style error handling without resorting to 3rd party libraries.
-
-**Non-nullable value type**:
-
-If the result of `doSomethingSync` is non-nullable, then we can write somewhat concise code:
-
-```kotlin
-val data: Data? = try { 
-        doSomethingSync() 
-    } catch(e: Throwable) { 
-        showErrorDialog(e)
-        null 
-    }
-if (data != null)    
-    processData(data) 
-```
-
-**Nullable value type**:
-
-If the result of `doSomethingSync` is nullable, then one possible alternative is shown below: 
-
-```kotlin
-var data: Data? = null
-val success = try { 
-        data = doSomethingSync()
-        true 
-    } catch(e: Throwable) { 
-        showErrorDialog(e)
-        false 
-    }
-if (success)    
-    processData(data) 
-```
-
-## API details
-
-The following snippet gives summary of all the public APIs:
-
-```kotlin
-@JvmInline value class Result<out T> /* internal constructor */ {
-    val isSuccess: Boolean
-    val isFailure: Boolean
-    fun getOrNull(): T?
-    fun exceptionOrNull(): Throwable?
-    
-    companion object {
-        fun <T> success(value: T): Result<T>
-        fun <T> failure(exception: Throwable): Result<T>
-    }
-}
-
-inline fun <R> runCatching(block: () -> R): Result<R>
-inline fun <T, R> T.runCatching(block: T.() -> R): Result<R>
-
-fun <T> Result<T>.getOrThrow(): T
-fun <R, T : R> Result<T>.getOrDefault(defaultValue: R): R
-
-inline fun <R, T : R> Result<T>.getOrElse(onFailure: (exception: Throwable) -> R): R
-inline fun <R, T> Result<T>.fold(onSuccess: (value: T) -> R, onFailure: (exception: Throwable) -> R): R
-
-inline fun <R, T> Result<T>.map(transform: (value: T) -> R): Result<R>
-inline fun <R, T: R> Result<T>.recover(transform: (exception: Throwable) -> R): Result<R>
-
-inline fun <R, T> Result<T>.mapCatching(transform: (value: T) -> R): Result<R>
-inline fun <R, T: R> Result<T>.recoverCatching(transform: (exception: Throwable) -> R): Result<R>
-
-inline fun <T> Result<T>.onSuccess(action: (value: T) -> Unit): Result<T>
-inline fun <T> Result<T>.onFailure(action: (exception: Throwable) -> Unit): Result<T>
-```
-
-The functions have self-explanatory consistent names that follow established tradition in the Kotlin Standard library
-and establish the following additional conventions:
-
-* Functions that can throw previously suppressed (captured) exception are named 
-  with explicit `OrThrow` suffix like `getOrThrow`.
-* Functions that capture thrown exception and encapsulate it into `Result` instance are named 
-  with explicit `Catching` suffix like `runCatching` and `mapCatching`.
-* A traditional `map` transformation function that works on successful cases 
-  is augmented with a `recover` function that similarly transforms exceptional cases. 
-  A failure inside either `map` or `recover` transform aborts operation like a traditional function, 
-  but `mapCatching` and `recoverCatching` encapsulate failure in transform into the resulting `Result`.
-* Functions to query the case are naturally named `isSuccess` and `isFailure`. 
-* Functions that act on the success or failure cases are named `onSuccess` and `onFailure` and return their receiver
-  unchanged for further chaining according to tradition established by `onEach` extension from the Standard Library.  
-  
-String representation of the `Result` value (`toString`) is either `Success(v)` or `Failure(x)` where `v` and `x` are 
-the string representations of the corresponding value and exception. `equals` and `hashCode` are implemented 
-naturally for the result type, comparing the corresponding values or exceptions.
-
-## Dependencies
-
-This library depends on 
-[`@JvmInline value class`](https://github.com/kotlin/KEEP/blob/master/proposals/inline-classes.md) 
-language feature for its efficient implementation. 
-
-## Limitations (legacy)
-
-In versions before Kotlin 1.5 `Result<T>` cannot be used as a direct result type of Kotlin functions, properties of 
-`Result` type are also restricted:
-
-```kotlin
-fun findUserByName(name: String): Result<User> // ERROR: 'kotlin.Result' cannot be used as a return type 
-fun foo(): Result<List<Int>> // ERROR 
-fun foo(): Result<Int>? // ERROR
-var foo: Result<Int> // ERROR
-```
-
-However, functions that use `Result` type in generic containers or receive result as a parameter type 
-were allowed:
-
-```kotlin
-fun findIntResults(): List<Result<Int>> // Ok
-fun receiveIntResult(result: Result<Int>) // Ok
-```
-
-Functions that declare generic result types may, in fact, return values of `Result` type when the
-`Result` type is substituted in place of their generic type parameters:
-
-```kotlin
-private val first: Result<Int> = findIntResults().first() // Ok, even though `first` is of type Result<Int>
-```
-
-Private and local properties of `Result`  type were allowed as long as they did not have custom getters:
-
-```kotlin
-private var foo: Result<Int> // Ok
-```
-
-The use of Kotlin null-safety operators `?.`, `?:` and `!!` was not allowed on both nullable and non-null `Result` types:
-
-```kotlin
-val r: Result<String?> = runCatching { readLine() }
-println(r!!) // ERROR
-```
- 
-The rationale behind these limitations was that future versions of Kotlin might wish to expand and/or change semantics
-of functions that return `Result` type and null-safety operators may change their semantics when used
-on values of `Result` type. In order to avoid breaking existing code in the future releases of Kotlin and leave door open 
-for those changes, the corresponding uses produced an error. Exceptions to this rule were made for carefully-reviewed
-declarations in the standard library that are part of the `Result` type API itself. 
-
-**UPDATE**: These limitations are lifted since Kotlin 1.5.  
-
-See [Future advancements](#future-advancements) for details on specific plans on updates on them.
-
-## Binary contract and implementation details
-
-`Result<T>` is implemented by an `@JvmInline value class` and is optimized for a successful case. Success is stored as
-a value of type `T` directly, without additional boxing, while failure exception is wrapped into an internal 
-`Result.Failure` class that is not exposed through binary interface and may be changed later. 
-
-`Result` class has the following internal published APIs that 
-represent its binary interface on JVM in addition to its public [API](#api-details):
-
-```kotlin
-@JvmInline value class Result<out T> @PublishedApi internal constructor(
-    @PublishedApi internal val value: Any? // internal value -- either T or Failure
-) : Serializable
-
-@PublishedApi internal fun createFailure(exception: Throwable): Any
-@PublishedApi internal fun Result<*>.throwOnFailure()
-```  
-
-## Error-handling style and exceptions
-
-The `Result` class is designed to capture generic failures of Kotlin functions for their latter processing and
-should be used in general-purpose API like futures, etc, that deal with invocation of Kotlin code blocks and
-must be able to represent both a successful and a failed result of execution. The `Result` class is not
-designed to represent domain-specific error conditions.
-
-In general, if some API requires its callers to handle failures locally (immediately around or next to the invocation), 
-then it should use nullable types, when these failures do not carry additional business meaning, 
-or domain-specific data types to represent its successful results and failures with any additional business-related
-data that is needed to process these failures.  
-
-Consider this hypothetical API design:
-
-```kotlin
-fun findUserByName(name: String): Result<User> // ERROR 
-```
-
-If the only kind of failure we might be interested in handling is the failure to find 
-the user with the given name, then the following signature shall be used:
-
-```kotlin
-fun findUserByName(name: String): User? // Ok
-```   
-   
-If there is a business need to distinguish different failures and process these different failures in distinct ways
-on each invocation site, then the following kind of signature shall be considered:
-
-```kotlin
-sealed class FindUserResult {
-    data class Found(val user: User) : FindUserResult()
-    data class NotFound(val name: String) : FindUserResult()
-    data class MalformedName(val name: String) : FindUserResult()
-    // other cases that need different business-specific handling code
-}
-
-fun findUserByName(name: String): FindUserResult
-```
-
-_Exceptions_ in Kotlin are designed for the failures that usually do not require local handling at each call site.
-This includes several broad areas &mdash; logic and programming errors like index bounds problems and various checks
-for internal invariants and preconditions, environment problems, out of memory conditions, etc. 
-These failures are usually non-recoverable (or are not supposed to be recovered from) and are handled in some 
-centralized way by logging or otherwise reporting them for troubleshooting, typically terminating application
-or, sometimes, attempting to restart or to reinitialize an application as a whole or just its failing subsystem.       
-This is where default exceptions behaviour to abort current operation and propagate it up the call stack comes in handy. 
-
-External environment problems like network or file input/output errors represent a corner case here. 
-It is cumbersome to require their local handling by the caller as it complicates sequential business 
-logic by obscuring it with code to handle IO errors, so it is idiomatic in Kotlin to use exceptions (like `IOException`) 
-for these. However, they are often handled at a more granular level than some global error-handling code. 
-These errors often require some specific user-interaction and can require domain-specific retry or recovery code.
-
-> Exceptions are also very expensive _to create_, but relatively cheap to _throw_, because they carry a lot of 
-additional metadata, like stack trace and message to aid in debugging. They are extremely valuable when this 
-metadata is written to the log for developers to aid in troubleshooting, but all that metadata is useless if
-exception is to be consumed by some business-logic to make some business-decision based simple on the presence of 
-exception. Use nullable types or domain-specific classes to represent failures that need specific handling.
-
-So, in case when `findUserByName` failure does not require local handling by the caller, then its failure 
-should be represented by exception and its signature should look like this:
-
-```kotlin
-fun findUserByName(name: String): User
-```
-
-> This signature is fine if we always sure that user shall be found, unless we have bugs, environment or IO issues.
-
-If invoker of this function wants to perform multiple operations and process their failures afterwards
-(without aborting on the first failure), it can always use `runCatching { findUserByName(name) }` 
-to make it explicit that a failure is being caught and
-encapsulated into `Result` instance. 
-
-## Similar API review
-
-Kotlin Standard Library provides rich collection of transformations for nullable types that are idiomatic in Kotlin
-to indicate failure when no additional information about the failure is needed. However, there is no build-in support
-for non-standard exception handling in the Standard Library -- exceptions always terminate operation and propagate to the caller.
-
-Other programming languages include a similar facility to represent a union of success and failure in their standard 
-library with the following names:
-
-* [`Try[T]`](https://www.scala-lang.org/api/current/scala/util/Try.html) in Scala is similar to the proposed `Result<T>`.
-* [`Result<T, E>`](https://doc.rust-lang.org/std/result/) in Rust (also parametrized by the type of error).
-* [`Exceptional e t`](https://wiki.haskell.org/Exception) in Haskell (also parametrized by the type of error).  
-* [`expected<E, T>`](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4015.pdf) in C++ (proposed, also parametrized by the type of error).
-
-Existing Kotlin libraries that provide similar functionality:
-
-* [`Try<T>`](https://arrow-kt.io/docs/datatypes/try/) from [Arrow](https://github.com/arrow-kt/arrow) library.
-* [`Result<T, E>`](https://github.com/kittinunf/Result) from @kittinunf. 
-
-> Note, that both of the libraries above promote "Railway Oriented Programming" 
-style with monads and their transformations, which heavily relies on functions returning `Try`, `Result`, etc.
-This programming style can be implemented and used in Kotlin via libraries as the above examples demonstrate.
-However, core Kotlin language and its Standard Library are designed around a _direct_ programming 
-[style](#error-handling-style-and-exceptions) in mind. 
-The general approach in Kotlin is that alternative programming styles
-should be provided as 3rd party libraries and DSLs. 
-
-For a more detailed comparison of Scala's `Try` and its Kotlin analogue in Arrow library with this `Result` class
-see [Appendix](#appendix-why-flatmap-is-missing). 
-
-## Placement
-
-This API shall be placed into the Kotlin Standard Library. Since the proposed API is fairly small and does not
-clearly belong to any larger group of APIs, it should be placed directly into `kotlin` package.  
-
-## Open issues
-
-This section lists open issues about this design.
-
-### Parameterization by the base error type
-
-Parameterizing this class by the type of exception like `Result<T, E>` is possible, but raises the
-following problems:
-    
-* It increases verboseness without providing improvement for any of the outlined [Use cases](#use-cases).
-* Kotlin currently lacks facility to specify default values for generic type parameters.
-* It leads to abuse in cases where a user-provided API-specific sealed class would work better.   
-
-It is possible to define a separate class like `ResultEx<T, E>` that is parametrized by 
-both successful type `T` and failed type `E` (that must extend `Throwable`)
-and then define `Result<T>` and a `typealias` to `ResultEx<T, Throwable>`.
-However, this creates its own problems:
-
-* Typealiases are quite verbosely rendered by IDE in signatures and there is no clear way on making them better.   
-* We cannot succinctly define `runCatching` function 
-  and other `Catching` functions to make them usable both with and without explicit caught type specification.
-  We'll have to have two different names for such a function: one for a function with an additional `E: Throwable` 
-  type parameter that must be specified and another one without it. Moreover, specifying `E` on call site requires 
-  specifying return type, too, since partial type parameter specification is not currently possible in Kotlin.  
-
-All in all, it does not seem that the costs outweigh whatever benefits it might bring.
-
-> Defining an even more general `Either<L, R>` type as a discriminated union between two arbitrary types 
-`L` and `R` and then using `typealias Result<T> = Either<Throwable, T>` raises similar problems with 
-an additional burden of designing functions for `Either` that would not needlessly pollute the namespace
-of functions applicable to `Result`. We don't have sufficient motivating use-cases for having
-`Either` in the Kotlin Standard Library beyond theoretical desire to base `Result` upon it. 
-
-### Result must be used
-
-Using `Result` as the return type of `Catching` functions poses a problem that it might accidentally get lost, 
-thus losing unhandled exception. 
-
-Consider this code from [Functional bulk manipulation of failures](#functional-bulk-manipulation-of-failures):
-
-```kotlin                                                     
-readFilesCatching(files).map { result ->
-    result.map { it.doSomething() } 
-}
-```
-
-If `doSomething` here throws an exception, then all exceptions that were returned in a list by `readFilesCatching` are lost.
-
-Some IDE inspections can be designed to detect these kinds of problems. 
-It is an open question how exactly they should
-work and and whether it is really a big problem after all.
-
-### Additional APIs for collections
-
-API for `Result` class is designed to be quite bare-bones.
-However, according to [Functional bulk manipulation of failures](#functional-bulk-manipulation-of-failures) use-case,
-one might occasionally encounter `List<Result<T>>` or another collection of `Result` instances. 
-It is open question whether we should provide additional extensions in the Standard Library to represent common
-operations on such collections and what those operations might be. 
-
-## Future advancements
-
-This section lists potential directions for future enhancement. None of them are worked out at the moment
-and all of them are purely tentative.
-
-### Representing as a sealed class
-
-Kotlin `@JvmInline value` classes cannot be currently used with `sealed class` construct. 
-If that is supported in the future, then we could change implementation of 
-`Result` without affecting its public APIs and binary interfaces in the following way:
-
-```kotlin
-@JvmInline sealed value class Result<T> {
-    @JvmInline class Success<T>(val value: T) : Result<T>()
-    class Failure<T>(val exception: Throwable) : Result<T>()
-}
-``` 
-
-> Notice, that only `Success` case is marked with `@JvmInline` annotation here. That is the case that should be
-represented without boxing. In general, if `@JvmInline sealed value` classes are allowed in the future,
-then Kotlin compiler could only support `@JvmInline` annotation on a set of subclasses with pairwise non-intersecting 
-types of their primary constructor properties. In particular, both `Success` and `Failure` cannot be `@JvmInline` 
-at the same time, since we would not be able to distinguish `Success(Exception(...))` from 
-`Failure(Exception(...))` at run time.
-
-These changes would make it possible to use `result is Success` and `result is Failure` expressions and get advantage of
-smart casts instead of `result.isSuccess` and `result.isFailure` that are currently provided and which do not work 
-with smart casts.
-
-### Parameterizing by the base error type
-
-If `Kotlin` adds some form of support for type parameter default values and partial type inference,
-then we can consider extending `Result` class with an additional type parameter `E: Throwable` that represents
-the base class for caught exceptions. For example, in input/output code there may be a desire to catch only 
-`IOException` and its subclasses, while aborting on any other exception using something like
-`runCatching<_, IOException> { code }` assuming that return type can be still inferred
-(potential partial type inference syntax here is used for illustration only).
-
-### Integration into the language
-
-Kotlin nullable types have extensive support in Kotlin via operators `?.`, `?:`, `!!`, and `T?` type constructor
-syntax. We can envision better integration of `Result` into the Kotlin language in the future.
-However, unlike nullable types, that are often used to represent _non signalling_ failure that does not cary
-additional information, `Result` instances also carry additional information and, in general, shall be
-always handled in some way. Making `Result` an integral part of the language also requires a 
-considerable effort on improving Kotlin type system to ensure proper handling of encapsulated exceptions.
-
-**UPDATE**: We have reached a decision of not following this road for a foreseeable future and will not pursue integration
-of any special constructions into the language that are tied to the `Result` type. As a part of the standard library 
-a `Result` type will stay narrowly-focused on the use-cases that are described at the beginning of this document, 
-abandoning ambitions to become any kind of universal error-handling primitive. We are working in other directions
-of making signalling error handling more pleasant to use in Kotlin. 
-The text below is left for historical reasons. 
-
-One potential direction is to allow  return value of `Result` type, 
-so that with parametrization by the base error type one can write:
-
-```kotlin
-fun findUserByName(name: String): Result<User, IOException>
-``` 
-
-This declaration would be conceptually equivalent to a Java function that is declared with `User` 
-result type and `throws IOException` annotation.
-However, unlike `throws` annotation in Java, `Result<User, IOException>` is going to 
-be considered a _return type_ of this function that explicitly declares exception that must be handled locally.
-There will be no silent propagation of that exception type up to the caller. The caller will be 
-required to handle it explicitly. When one writes:
-
-```kotlin
-val result = findUserByName(name)
-```  
-
-Then inferred type of `result` will be `Result<User, IOException>`. 
-Direct access to the `User` methods and extensions would not be possible,
-but all the `?.`, `?:`, and `!!` operators can be extended to work appropriately with `Result` type to 
-make the corresponding code fluent 
-in a similar way as it happens with nullable types today. Some additional operators might be required, too.
-
-Unlike checked exception in Java, these are going to be full-blown types, so they play nicely with collections
-(`List<Result<User, IOException>>` is going to be a valid type) 
-and all the higher-order functions in Kotlin will work properly with those types without the problems
-that made it impossible to properly integrate checked exceptions with Java generics. 
-
-Moreover, it can be very efficiently implemented on JVM in the return type position by actually throwing the corresponding
-exception inside and catching it outside, on the caller side, so no boxing will be required even for primitive
-results. "Rethrowing" exceptions with `!!` can be transparent in JVM bytecode in the same way as it
-happens in Java programs using exceptions.
-
-> **Update note**: This proves virtually impossible to implement correctly, as there would be no way to distinguish
-> a domain-specific error that needs to be represented in the `Result` type for handling it by the caller from the 
-> logic error in the code (a crash) that shall still be represented as exception to be handled in a centralized place
-> of the application for logging, etc.
-
-All in all, it could provide a safe replacement for checked exceptions on JVM and open a path to a better
-integration with JVM APIs that rely on checked exceptions. However, details of this interoperability will have to 
-be worked out as there are lots of problems down this path. We cannot just lift all Java functions with `throws` into
-Kotlin functions with the corresponding `Result` type not only because of backwards compatibility, but also due to the way checked 
-exceptions are (ab)used in the JVM ecosystem, so are more fine-grained control for interoperability will have to 
-be designed.   
-
-It is all beyond the scope of this KEEP.
-
-## Appendix: Why flatMap is missing
-
-You can skip this appendix is you are not familiar with Scala's or Arrow's `Try` monad that provides very 
-similar functionality to this `Result` class. 
-
-If you are familiar with `Try` monad, then you might ask why there is no `flatMap` 
-function on the `Result` class. This function could have been defined with the following signature:
-
-```kotlin
-inline fun <R, T> Result<T>.flatMap(transform: (T) -> Result<R>): Result<R>
-```  
-
-The usual reason to have `flatMap` is to avoid "nesting" of monadic types when combining multiple
-functions that return them, like in the following example:
-
-```kotlin
-runCatching { d.await() }.map { it.doSomethingCatching() } // : Result<Result<Data>> -- oops!
-``` 
- 
-Functional code that uses `Try` monad gets quickly polluted
-with `flatMap` invocations. To make such code manageable, a functional programming language is usually extended 
-with monad comprehension syntax to hide those `flatMap` invocations.  
-
-Take a look at the following example code that
-uses monad comprehension over `Try` monad 
-(which is adapted from a guide 
-[here](https://danielwestheide.com/blog/2012/12/26/the-neophytes-guide-to-scala-part-6-error-handling-with-try.html)):
- 
-```scala
-def getURLContent(url: String): Try[Iterator[String]] =
-  for {
-    url <- parseURL(url) // here parseURL returns Try[URL], encapsulates failure
-    connection <- Try(url.openConnection())
-    input <- Try(connection.getInputStream)
-    source = Source.fromInputStream(input)
-  } yield source.getLines()
-```
-
-Adapting functions used here to Kotlin style, one can write this code in Kotlin, 
-with the same semantics of aborting further progress on the first failure, in the following way:
-
-```kotlin
-fun getURLContent(url: String): List<String> {
-    val url = parseURL(url) // here parseURL returns URL, throws on failure
-    val connection = url.openConnection()
-    val input = connection.getInputStream()
-    val source = Source.fromInputStream(input)
-    return source.getLines()
-}
-```
-
-Notice, that monad comprehension over `Try` monad is basically built into the Kotlin language.
-That is how imperative control flow works in Kotlin out of the box and there is no need to emulate it
-via monad comprehensions. If callers of this function need an encapsulated failure,
-they can always use `runCatching { getURLContent(url) }` expression.
-
-However, the Kotlin is not exactly equivalent to the initial code with `Try`.
-Let us see what are the differences. The original `parseURL` have been returning an encapsulated exception
-and it could be making a _fine grained_ decision on which kinds of exceptions shall be encapsulated into the result
-and which kinds of exceptions shall be thrown. Rewritten code propagates any failure in `parseURL` up to the caller 
-without this fine grained distinction between different kinds of failures. There is also a subtle difference on
-the `fromInputStream` invocation. Original code would fail with exception if this invocation fails, while any failure
-in `openConnection` and `getInputStream` is encapsulated into the result of the function via `Try`. Rewritten code 
-does not make distinctions between different kinds of failures anymore.
-
-All in all, the differences can be summarized as follows. `Result` is a blunt tool designed to catch
-any failure in the function invocation for the processing later on.
-On the other hand, libraries like [Arrow](https://arrow-kt.io) provide utility classes like `Try` and the 
-corresponding extension functions that enable more fine-grained control. When a function is declared with `Try<T>`
-as its result type, it means that this function can make a fine-grained decision on which failures are encapsulated
-and which failures are thrown up the call stack.       
-
-If your code needs fine-grained exception handling policy, we'd recommend designing your code in such a way, that
-exceptions are not used at all for any kinds of locally-handled failures 
-(see section on [style](#error-handling-style-and-exceptions) for example code
-with nullable types and sealed data classes). In the context of this appendix, `parseURL` could return a nullable
-result (of type `URL?`) to indicate parsing failure or return its own purpose-designed sealed class that would provide 
-all the additional details about failure (like the exact failure position in input string) 
-if that is needed for some business function 
-(like setting cursor to the place of failure in the user interface).
-In cases when you need to distinguish between different kinds of failures and these approaches do not work for you, 
-you are welcome to write your own utility libraries or use libraries like [Arrow](https://arrow-kt.io) 
-that provide the corresponding utilities.    
-
-## Revision history
-
-* **Kotlin 1.5**
-  * Allow returning the `Result` type from functions.
-  * Allow Kotlin null-safety operators `?.`, `?:` and `!!` on both nullable and non-null `Result` types.
-  * Text updated to replace `inline class` with `@JvmInline value class`.
+Redirect to [KEEP-0127-result.md](KEEP-0127-result.md)