@orbital_mcp/patchrelay 0.0.0-stage → 0.1.0-alpha05

package/.patchrelay-tools/build.gradle

@@ -0,0 +1,22 @@
+plugins { id 'groovy'; id 'java-gradle-plugin'; id 'org.jetbrains.kotlin.jvm' version '1.9.23' }
+repositories { google(); mavenCentral() }
+dependencies {
+    implementation localGroovy()
+    implementation 'org.jetbrains.kotlin:kotlin-compiler-embeddable:1.9.23'
+    testImplementation 'junit:junit:4.13.2'
+    compileOnly 'com.android.tools.build:gradle-api:8.6.0'
+}
+java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }
+kotlin { jvmToolchain(17) }
+gradlePlugin {
+    plugins {
+        functions {
+            id = 'dev.patchrelay.functions'
+            implementationClass = 'dev.patchrelay.gradle.FunctionsPlugin'
+        }
+        baseline {
+            id = 'dev.patchrelay.baseline'
+            implementationClass = 'dev.patchrelay.gradle.PatchRelayPlugin'
+        }
+    }
+}

package/.patchrelay-tools/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'patchrelay-build-tools'

package/.patchrelay-tools/src/main/groovy/dev/patchrelay/gradle/FunctionsPlugin.groovy

@@ -0,0 +1,328 @@
+package dev.patchrelay.gradle
+
+import groovy.json.JsonOutput
+import org.gradle.api.*
+import org.gradle.api.tasks.*
+import org.gradle.api.file.FileCollection
+import org.jetbrains.kotlin.cli.jvm.compiler.KotlinCoreEnvironment
+import org.jetbrains.kotlin.cli.jvm.compiler.EnvironmentConfigFiles
+import org.jetbrains.kotlin.config.CompilerConfiguration
+import org.jetbrains.kotlin.com.intellij.openapi.util.Disposer
+import org.jetbrains.kotlin.psi.*
+import org.jetbrains.kotlin.lexer.KtTokens
+
+/** Kotlin PSI reads declarations; Kotlin/JVM and Kotlin/JS still type-check all bodies. */
+class FunctionBindings {
+    static List<Map> inspect(Map<String, String> sources) { discover(sources).functions }
+
+    static Map discover(Map<String, String> sources, boolean compose = false) {
+        def disposable = Disposer.newDisposable()
+        try {
+            def env = KotlinCoreEnvironment.createForProduction(disposable, new CompilerConfiguration(), EnvironmentConfigFiles.JVM_CONFIG_FILES)
+            def factory = new KtPsiFactory(env.project, false)
+            def bindings = []
+            def states = []
+            def entrypoints = new HashSet<String>()
+            sources.toSorted().each { path, text ->
+                def file = factory.createFile(path, text.replace('\r\n', '\n').replace('\r', '\n'))
+                if (compose && file.importDirectives.any { it.importedFqName?.asString()?.startsWith('androidx.compose.') && !it.importedFqName.asString().startsWith('androidx.compose.runtime') })
+                    throw new GradleException("PatchRelay $path: only Compose runtime and dev.patchrelay.compose widgets are supported; Android Material/UI requires a different backend")
+                if (compose && file.importDirectives.any { it.importedFqName?.asString() in ['androidx.compose.runtime.LaunchedEffect', 'androidx.compose.runtime.produceState', 'androidx.compose.runtime.rememberCoroutineScope', 'androidx.compose.runtime.snapshotFlow'] })
+                    throw new GradleException("PatchRelay $path: asynchronous Compose effects are unsupported, including aliased imports; use installed host operations")
+                if (file.importDirectives.any { it.aliasName && it.importedFqName?.shortName()?.asString() == 'PatchFunction' })
+                    throw new GradleException("PatchRelay $path: annotation aliases are unsupported; use @PatchFunction")
+                def visit
+                visit = { element ->
+                    if (!compose && element instanceof KtNamedFunction && element.annotationEntries.any { it.shortName?.asString() == 'Composable' })
+                        throw new GradleException("PatchRelay $path: ${element.name}: Compose runtime/backend is unsupported; use the shared screen-tree DSL or keep Compose in the installed native host")
+                    if (compose && element instanceof KtCallExpression && element.calleeExpression?.text in ['LaunchedEffect', 'produceState', 'rememberCoroutineScope', 'snapshotFlow'])
+                        throw new GradleException("PatchRelay $path: ${element.calleeExpression.text}: asynchronous Compose effects are unsupported; use installed host operations and explicit render/event transactions")
+                    if (element instanceof KtNamedFunction && element.parent instanceof KtFile) {
+                        if (element.name?.startsWith('patchRelayIntercept_') || element.name?.startsWith('__patchrelay_original_'))
+                            throw new GradleException("PatchRelay $path: reserved compiler-generated function name: ${element.name}")
+                        entrypoints.add(element.name)
+                    }
+                    if (element instanceof KtProperty && element.annotationEntries.any { it.shortName?.asString() == 'PatchState' }) {
+                        def property = element
+                        def annotation = property.annotationEntries.find { it.shortName?.asString() == 'PatchState' }
+                        String target = (file.packageFqName.asString() ? file.packageFqName.asString() + '.' : '') + property.name
+                        String id = target.toLowerCase(Locale.ROOT)
+                        if (annotation.valueArguments) {
+                            def expression = annotation.valueArguments.size() == 1 ? annotation.valueArguments[0].getArgumentExpression() : null
+                            if (!(expression instanceof KtStringTemplateExpression) || expression.entries.any { !(it instanceof KtLiteralStringTemplateEntry) })
+                                throw new GradleException("PatchRelay $path: state ID must be a literal string")
+                            id = expression.entries.collect { it.text }.join('')
+                        }
+                        if (!(property.parent instanceof KtFile) || !property.isVar() || !property.initializer || property.accessors || property.hasDelegate() ||
+                            property.hasModifier(KtTokens.PRIVATE_KEYWORD) || !supportedType(property.typeReference?.text, false) ||
+                            !property.name?.matches('[a-zA-Z][a-zA-Z0-9_]*') || !id.matches('[a-z][a-z0-9_.-]{0,95}'))
+                            throw new GradleException("PatchRelay $path: @PatchState requires a top-level mutable scalar with explicit type, initializer and no custom accessors")
+                        states << [id:id, target:target, type:property.typeReference.text]
+                    }
+                    if (element instanceof KtNamedFunction && element.annotationEntries.any { it.shortName?.asString() == 'PatchFunction' }) {
+                        def fn = element
+                        def fail = { reason -> throw new GradleException("PatchRelay $path: ${fn.name}: $reason. Supported: public top-level function, 0..8 scalar arguments, explicit scalar/Unit return type") }
+                        if (!(fn.parent instanceof KtFile) || fn.receiverTypeReference || fn.typeParameters ||
+                            fn.hasModifier(KtTokens.PRIVATE_KEYWORD) || fn.hasModifier(KtTokens.INTERNAL_KEYWORD) || fn.hasModifier(KtTokens.EXPECT_KEYWORD) || fn.hasModifier(KtTokens.EXTERNAL_KEYWORD) || fn.hasModifier(KtTokens.INLINE_KEYWORD)) fail('unsupported function declaration (inline interception is unsupported)')
+                        def parameters = fn.valueParameters.collect { it.typeReference?.text }
+                        String result = fn.typeReference?.text
+                        if (!fn.name?.matches('[a-zA-Z][a-zA-Z0-9_]*') || !fn.hasBody() || fn.valueParameters.size() > 8 ||
+                            !supportedType(result, true) || parameters.any { !supportedType(it, false) } ||
+                            fn.valueParameters.any { it.defaultValue || it.isVarArg() }) fail('use Int, finite Double, Boolean, String, nullable scalars or Unit result; no defaults or varargs')
+                        def annotation = fn.annotationEntries.find { it.shortName?.asString() == 'PatchFunction' }
+                        def args = annotation.valueArguments
+                        String qualified = (file.packageFqName.asString() ? file.packageFqName.asString() + '.' : '') + fn.name
+                        String id = qualified.toLowerCase(Locale.ROOT) + '.v1'
+                        if (args) {
+                            def expression = args.size() == 1 ? args[0].getArgumentExpression() : null
+                            if (!(expression instanceof KtStringTemplateExpression) || expression.entries.any { !(it instanceof KtLiteralStringTemplateEntry) }) fail('ID must be a literal string')
+                            id = expression.entries.collect { it.text }.join('')
+                        }
+                        if (!id.matches('[a-z][a-z0-9_.-]{0,95}')) fail('ID must match [a-z][a-z0-9_.-]{0,95}')
+                        boolean suspending = fn.hasModifier(KtTokens.SUSPEND_KEYWORD)
+                        bindings << [id:id, signature:(suspending ? 'suspend ' : '') + '(' + parameters.join(',') + ')->' + result,
+                            target:qualified, name:fn.name, parameters:parameters, result:result, suspending:suspending]
+                    }
+                    element.children.each { visit(it) }
+                }
+                visit(file)
+            }
+            if (bindings.size() > 64) throw new GradleException('PatchRelay supports at most 64 @PatchFunction declarations')
+            if (bindings*.id.toSet().size() != bindings.size() || bindings*.name.toSet().size() != bindings.size()) throw new GradleException('PatchRelay duplicate function ID or hook name; overloads are unsupported')
+            if (entrypoints.contains('main')) throw new GradleException('PatchRelay owns the JS main entrypoint; move application initialization into the screen module')
+            if (entrypoints.contains('takeHostRequests') != entrypoints.contains('handleHostResult')) throw new GradleException('PatchRelay host protocol requires both takeHostRequests and handleHostResult')
+            if (states.size() > 32 || states*.id.toSet().size() != states.size()) throw new GradleException('PatchRelay state IDs must be unique; maximum 32 values')
+            [functions:bindings.sort { it.id }, hostCalls:entrypoints.contains('takeHostRequests'), states:states.sort { it.id }, migration:entrypoints.contains('migrateAppState')]
+        } finally { Disposer.dispose(disposable) }
+    }
+
+    static boolean supportedType(String type, boolean result) {
+        type != null && (type in ['Int', 'Double', 'Boolean', 'String', 'Int?', 'Double?', 'Boolean?', 'String?'] || (result && type == 'Unit'))
+    }
+
+    static String decode(String type, String value) {
+        if (type == 'Unit') return "patchRelayUnit($value)"
+        String name = type.replace('?', '')
+        type.endsWith('?') ? "patchRelayNullable($value, ::patchRelay$name)" : "patchRelay$name($value)"
+    }
+
+    static String encode(String type, String value) { type == 'Unit' ? "run { $value; JsonNull }" : "JsonPrimitive($value)" }
+
+    static void generate(List<Map> bindings, File output, boolean hostCalls = false, List<Map> states = [], boolean migration = false) {
+        File common = new File(output, 'common/PatchRelayFunctions.kt')
+        File js = new File(output, 'js/PatchRelayExports.kt')
+        common.parentFile.mkdirs(); js.parentFile.mkdirs()
+        String imports = bindings.withIndex().collect { b, index -> "import ${b.target} as patchRelayNative$index" }.join('\n')
+        imports += '\n' + states.withIndex().collect { state, index -> "import ${state.target} as patchRelayState$index" }.join('\n')
+        String schema = Contract.hash(JsonOutput.toJson(states.collect { [it.id, it.type] }).getBytes('UTF-8'))
+        String restore = states.withIndex().collect { state, index -> '    val state' + index + ' = ' + decode(state.type, 'values["' + state.id + '"] ?: error("Missing state")') }.join('\n') + '\n' +
+            states.withIndex().collect { state, index -> "    patchRelayState$index = state$index" }.join('\n')
+        String stateCode = """
+internal fun patchRelayExportState(): String = patchRelayText(JsonObject(mapOf(
+    "schema" to JsonPrimitive("$schema"), "values" to JsonObject(mapOf(${states.withIndex().collect { state, index -> '"' + state.id + '" to ' + encode(state.type, "patchRelayState$index") }.join(', ')})))))
+internal fun patchRelayRestoreState(snapshot: String): String {
+    val root = patchRelayParse(snapshot) as? JsonObject ?: error("Expected state object")
+    val schema = patchRelayString(root["schema"] ?: error("Missing state schema"))
+    val oldValues = root["values"] as? JsonObject ?: error("Missing state values")
+    val values = if (schema == "$schema") oldValues else ${migration ? 'migrateAppState(schema, oldValues)' : 'return "incompatible"'}
+    require(values.keys == setOf<String>(${states.collect { '"' + it.id + '"' }.join(', ')})) { "Wrong state fields" }
+$restore
+    return "restored"
+}
+"""
+        String hooks = bindings.withIndex().collect { b, index ->
+            String params = b.parameters.withIndex().collect { type, n -> "arg$n: $type" }.join(', ')
+            String args = b.parameters.indices.collect { "arg$it" }.join(', ')
+            String call = "patchRelayNative$index($args)"
+            String encodedArgs = b.parameters.withIndex().collect { type, n -> encode(type, "arg$n") }.join(', ')
+            """    fun ${b.name}(${params ? params + ', ' : ''}dispatch: PatchRelayDispatch? = null, onResult: (${b.result}) -> Unit) {
+        val native: suspend () -> ${b.result} = { $call }
+        if (dispatch == null) native.startCoroutine(Continuation(EmptyCoroutineContext) { onResult(it.getOrThrow()) })
+        else dispatch("${b.id}", patchRelayText(JsonArray(listOf($encodedArgs))), { done ->
+            native.startCoroutine(Continuation(EmptyCoroutineContext) { result -> done(result.map { value -> patchRelayText(${encode(b.result, 'value')}) }) })
+        }, { onResult(${decode(b.result, 'patchRelayParse(it)')}) })
+    }"""
+        }.join('\n')
+        String intercepted = bindings.findAll { it.suspending }.collect { b ->
+            String nativeName = 'patchRelayNative' + bindings.indexOf(b)
+            String params = b.parameters.withIndex().collect { type, n -> "arg$n: $type" }.join(', ')
+            String args = b.parameters.indices.collect { "arg$it" }.join(', ')
+            String encodedArgs = b.parameters.withIndex().collect { type, n -> encode(type, "arg$n") }.join(', ')
+            """suspend fun patchRelayIntercept_${b.name}($params): ${b.result} {
+    val dispatch = PatchRelayFunctions.dispatcher
+    if (dispatch == null) return $nativeName($args)
+    return suspendCoroutine { continuation ->
+        var completed = false
+        val finish: (Result<String>) -> Unit = { result ->
+            if (!completed) {
+                completed = true
+                continuation.resumeWith(result.mapCatching { ${decode(b.result, 'patchRelayParse(it)')} })
+            }
+        }
+        try {
+            dispatch("${b.id}", patchRelayText(JsonArray(listOf($encodedArgs))), { done ->
+                val native: suspend () -> ${b.result} = { $nativeName($args) }
+                native.startCoroutine(Continuation(EmptyCoroutineContext) { result -> done(result.mapCatching { value -> patchRelayText(${encode(b.result, 'value')}) }) })
+            }, finish)
+        } catch (failure: Throwable) { finish(Result.failure(failure)) }
+    }
+}"""
+        }.join('\n')
+        common.setText("""// Generated by PatchRelay. Do not edit.
+import kotlinx.serialization.json.*
+import kotlin.coroutines.*
+$imports
+@Target(AnnotationTarget.FUNCTION)
+@Retention(AnnotationRetention.BINARY)
+annotation class PatchFunction(val id: String = "")
+@Target(AnnotationTarget.PROPERTY)
+@Retention(AnnotationRetention.SOURCE)
+annotation class PatchState(val id: String = "")
+
+typealias PatchRelayDispatch = (String, String, ((Result<String>) -> Unit) -> Unit, (String) -> Unit) -> Unit
+typealias PatchRelaySuspendDispatch = (String, String, ((Result<String>) -> Unit) -> Unit, (Result<String>) -> Unit) -> Unit
+
+internal fun patchRelayParse(value: String): JsonElement { require(value.length <= 8192); return Json.parseToJsonElement(value) }
+internal fun patchRelayText(value: JsonElement): String = value.toString().also { require(it.length <= 8192) }
+internal fun patchRelayInt(value: JsonElement): Int { require(value is JsonPrimitive && !value.isString); return value.intOrNull ?: error("Expected Int") }
+internal fun patchRelayDouble(value: JsonElement): Double { require(value is JsonPrimitive && !value.isString); return (value.doubleOrNull ?: error("Expected Double")).also { require(it.isFinite()) } }
+internal fun patchRelayBoolean(value: JsonElement): Boolean { require(value is JsonPrimitive && !value.isString); return value.booleanOrNull ?: error("Expected Boolean") }
+internal fun patchRelayString(value: JsonElement): String { require(value is JsonPrimitive && value.isString); return value.content.also { require(it.length <= 4096) } }
+internal fun patchRelayUnit(value: JsonElement) { require(value == JsonNull) }
+internal fun <T> patchRelayNullable(value: JsonElement, read: (JsonElement) -> T): T? = if (value == JsonNull) null else read(value)
+
+$stateCode
+$intercepted
+object PatchRelayFunctions {
+    @kotlin.concurrent.Volatile private var installedDispatcher: PatchRelaySuspendDispatch? = null
+    internal val dispatcher: PatchRelaySuspendDispatch? get() = installedDispatcher
+    fun installDispatcher(dispatch: PatchRelaySuspendDispatch?) { installedDispatcher = dispatch }
+    val contracts: Map<String, String> = mapOf(${bindings.collect { '"' + it.id + '" to "' + it.signature + '"' }.join(', ')})
+    val ids: Set<String> get() = contracts.keys
+$hooks
+}
+""", 'UTF-8')
+        String ids = JsonOutput.toJson(bindings*.id)
+        String contracts = JsonOutput.toJson(bindings.collectEntries { [(it.id):it.signature] })
+        String cases = bindings.collect { b ->
+            String args = b.parameters.withIndex().collect { type, n -> decode(type, "args[$n]") }.join(', ')
+            '    "' + b.id + '" -> { require(args.size == ' + b.parameters.size() + '); ' + encode(b.result, b.target + '(' + args + ')') + ' }'
+        }.join('\n')
+        String legacy = bindings.findAll { it.signature == '(Int,Int)->Int' }.collect {
+            '    "' + it.id + '" -> ' + it.target + '(first, second).toString()'
+        }.join('\n')
+        js.setText("""@file:OptIn(kotlin.js.ExperimentalJsExport::class)
+import kotlin.js.JsExport
+import kotlin.js.Promise
+import kotlin.coroutines.*
+import kotlinx.serialization.json.*
+@JsExport
+fun renderScreen(screenId: String): String = renderAppScreen(screenId)
+@JsExport
+fun handleEvent(screenId: String, action: String, value: String? = null): String = handleAppEvent(screenId, action, value)
+@JsExport
+fun exportState(): String = patchRelayExportState()
+@JsExport
+fun restoreState(snapshot: String): String = patchRelayRestoreState(snapshot)
+@JsExport
+fun patchedFunctionIds(): String = ${JsonOutput.toJson(ids)}
+@JsExport
+fun patchedFunctionContracts(): String = ${JsonOutput.toJson(contracts)}
+@JsExport
+fun invokeFunction(functionId: String, arguments: String): Promise<String> = Promise { resolve, reject ->
+    val body: suspend () -> String = {
+        val args = patchRelayParse(arguments) as? JsonArray ?: error("Expected argument array")
+        require(args.size <= 8)
+        patchRelayText(when (functionId) {
+$cases
+            else -> error("Unknown function: \$functionId")
+        })
+    }
+    body.startCoroutine(Continuation(EmptyCoroutineContext) { result -> result.fold(resolve, reject) })
+}
+@JsExport
+fun invokePatch(functionId: String, first: Int, second: Int): String = when (functionId) {
+$legacy
+    else -> error("Unknown legacy integer function: \$functionId")
+}
+
+// Stable SDK registration is independent of the Kotlin project's output-module name.
+fun main() {
+    val api = js("({})")
+    api.exportState = ::exportState
+    api.restoreState = ::restoreState
+    api.renderScreen = ::renderScreen
+    api.handleEvent = ::handleEvent
+    api.patchedFunctionIds = ::patchedFunctionIds
+    api.patchedFunctionContracts = ::patchedFunctionContracts
+    api.invokeFunction = ::invokeFunction
+    api.invokePatch = ::invokePatch
+${hostCalls ? '    api.takeHostRequests = ::takeHostRequests\n    api.handleHostResult = ::handleHostResult' : ''}
+    js("globalThis").__patchrelay = api
+}
+""", 'UTF-8')
+        new File(output, 'functions.json').setText(JsonOutput.toJson([format:2, stateSchema:schema, state:states.collect { [id:it.id, type:it.type] }, functions:bindings.collect { [id:it.id, signature:it.signature] }]) + '\n', 'UTF-8')
+    }
+}
+
+abstract class GenerateFunctions extends DefaultTask {
+    @Input boolean compose
+    @InputDirectory File sources
+    @OutputDirectory File destination
+    @InputFiles FileCollection platformSources
+    @TaskAction void generate() {
+        if (!platformSources.empty) throw new GradleException('PatchRelay supports commonMain Kotlin only; platform implementations require a new native integration: ' + platformSources.files*.name)
+        def files = new TreeMap<String,String>()
+        sources.eachFileRecurse { if (it.isFile() && it.name.endsWith('.kt')) files[sources.toPath().relativize(it.toPath()).toString()] = it.getText('UTF-8') }
+        def program = FunctionBindings.discover(files, compose)
+        FunctionBindings.generate(program.functions, destination, program.hostCalls, program.states, program.migration)
+        def backend = new File(destination, 'common/PatchRelayCompose.kt')
+        if (compose) backend.setText(GenerateFunctions.getResourceAsStream('/patchrelay/ComposeScreens.kt').getText('UTF-8'), 'UTF-8')
+        else if (backend.exists()) backend.delete()
+    }
+}
+
+class FunctionsPlugin implements Plugin<Project> {
+    void apply(Project project) {
+        project.plugins.withId('org.jetbrains.kotlin.multiplatform') {
+            if (project.providers.gradleProperty('kotlin.js.ir.output.granularity').orNull != 'whole-program')
+                throw new GradleException('PatchRelay requires a self-contained program: add kotlin.js.ir.output.granularity=whole-program to gradle.properties')
+            def output = project.layout.buildDirectory.dir('generated/patchrelay')
+            boolean composeEnabled = project.providers.gradleProperty('patchrelay.compose').orNull == 'true'
+            def compilerJar = new File(FunctionsPlugin.protectionDomain.codeSource.location.toURI())
+            if (!compilerJar.isFile()) throw new GradleException('PatchRelay compiler plugin must run from its built JAR')
+            def task = project.tasks.register('generatePatchRelayFunctions', GenerateFunctions) {
+                sources = project.file('src/commonMain/kotlin')
+                platformSources = project.fileTree('src') { include 'jvmMain/**/*.kt', 'jsMain/**/*.kt', 'androidMain/**/*.kt' }
+                destination = output.get().asFile
+                compose = composeEnabled
+            }
+            def kotlin = project.extensions.getByName('kotlin')
+            if (kotlin.coreLibrariesVersion != '1.9.23') throw new GradleException('PatchRelay IR interception requires Kotlin 1.9.23; compiler upgrades require a matching plugin')
+            kotlin.sourceSets.getByName('commonMain').dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3' }
+            if (composeEnabled) {
+                kotlin.sourceSets.getByName('commonMain').dependencies { implementation 'org.jetbrains.compose.runtime:runtime:1.6.10' }
+                def composeCompiler = project.configurations.create('patchRelayComposeCompiler')
+                project.dependencies.add(composeCompiler.name, 'org.jetbrains.compose.compiler:compiler:1.5.13.5')
+                project.tasks.matching { it.name.startsWith('compileKotlin') || it.name.startsWith('compileTestKotlin') || it.name.startsWith('compileProductionExecutable') || it.name.startsWith('compileTestDevelopmentExecutable') }.configureEach {
+                    inputs.files(composeCompiler)
+                    kotlinOptions.freeCompilerArgs += ['-Xplugin=' + composeCompiler.singleFile.absolutePath]
+                }
+            }
+            kotlin.sourceSets.getByName('commonMain').kotlin.srcDir(output.map { it.dir('common') })
+            // jsMain exists after the consumer declares its JS target.
+            project.afterEvaluate {
+                kotlin.sourceSets.getByName('jsMain').kotlin.srcDir(output.map { it.dir('js') })
+            }
+            project.tasks.matching { it.name.startsWith('compileKotlin') || it.name.startsWith('compileProductionExecutable') || it.name.startsWith('compileTestKotlin') }.configureEach { dependsOn(task) }
+            kotlin.targets.all { target ->
+                if (target.platformType.toString() == 'jvm') target.compilations.matching { it.name == 'main' }.all { compilation ->
+                    compilation.compileTaskProvider.configure {
+                        inputs.file(compilerJar)
+                        kotlinOptions.freeCompilerArgs += ['-Xplugin=' + compilerJar.absolutePath]
+                    }
+                }
+            }
+        }
+    }
+}

package/.patchrelay-tools/src/main/groovy/dev/patchrelay/gradle/PatchRelayPlugin.groovy

@@ -0,0 +1,226 @@
+package dev.patchrelay.gradle
+
+import com.android.build.api.artifact.SingleArtifact
+import com.android.build.api.variant.BuildConfigField
+import groovy.json.JsonOutput
+import groovy.json.JsonSlurper
+import org.gradle.api.*
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.tasks.*
+import java.nio.file.Files
+import java.nio.file.StandardCopyOption
+import java.security.MessageDigest
+import java.util.zip.ZipEntry
+import java.util.zip.ZipFile
+import java.util.zip.ZipOutputStream
+
+class Contract {
+    static String hash(byte[] bytes) { MessageDigest.getInstance('SHA-256').digest(bytes).encodeHex().toString() }
+    static String fileHash(File file) {
+        def digest = MessageDigest.getInstance('SHA-256')
+        file.withInputStream { input ->
+            byte[] buffer = new byte[8192]
+            int length
+            while ((length = input.read(buffer)) != -1) digest.update(buffer, 0, length)
+        }
+        digest.digest().encodeHex().toString()
+    }
+    static Map read(File file) { new JsonSlurper().parse(file) as Map }
+    static File inside(File root, String path) {
+        File file = new File(root, path).canonicalFile
+        if (!file.toPath().startsWith(root.canonicalFile.toPath())) throw new GradleException('PatchRelay input escapes project directory')
+        file
+    }
+    static Map fingerprint(File root, List paths, List extensions) {
+        def files = new TreeMap<String,String>()
+        paths.each { path ->
+            File input = inside(root, path.toString())
+            if (!input.exists()) throw new GradleException("Missing PatchRelay input: $path")
+            def visit = { File file ->
+                inside(root, root.toPath().relativize(file.toPath()).toString())
+                if (Files.isSymbolicLink(file.toPath())) throw new GradleException('PatchRelay source links are unsupported')
+                String digest = (extensions.any { file.name.endsWith(it.toString()) }
+                    ? hash(file.getText('UTF-8').replace('\r\n','\n').getBytes('UTF-8')) : fileHash(file))
+                files[root.toPath().relativize(file.toPath()).toString().replace('\\','/')] = digest
+            }
+            if (input.isFile()) visit(input)
+            else input.eachFileRecurse { File file -> if (file.isFile()) visit(file) }
+        }
+        files
+    }
+}
+
+abstract class PrepareBaseline extends DefaultTask {
+    @OutputDirectory abstract DirectoryProperty getOutputDirectory()
+    @Internal Map options
+    @Internal def namespaceValue
+    @Internal def applicationId
+
+    @TaskAction void prepare() {
+        File root = project.rootDir
+        String namespace = namespaceValue.get()
+        String appId = applicationId.get()
+        Map runtime = Contract.read(Contract.inside(root, options.runtimeFile))
+        if (runtime.format != 1 || runtime.screenApi != 2 || runtime.appId != appId) throw new GradleException('PatchRelay runtime does not match this application variant')
+        File program = Contract.inside(root, options.programFile)
+        byte[] bytes = program.bytes
+        if (!bytes.length || bytes.length > 2 * 1024 * 1024) throw new GradleException('PatchRelay program must be 1 byte–2 MiB')
+        java.nio.charset.StandardCharsets.UTF_8.newDecoder().decode(java.nio.ByteBuffer.wrap(bytes))
+        File asset = Contract.inside(root, options.baselineAsset)
+        asset.parentFile.mkdirs()
+        if (!asset.isFile() || !Arrays.equals(asset.bytes, bytes)) Files.copy(program.toPath(), asset.toPath(), StandardCopyOption.REPLACE_EXISTING)
+        Map nativeFiles = Contract.fingerprint(root, runtime.nativeInputs, runtime.textExtensions)
+        Map screenFiles = Contract.fingerprint(root, options.screenInputs, runtime.textExtensions)
+        String host = Contract.hash(JsonOutput.toJson(nativeFiles).getBytes('UTF-8'))
+        File output = outputDirectory.get().asFile
+        output.mkdirs()
+        File source = new File(output, namespace.replace('.','/') + '/patchrelay/PatchRelayBuild.java')
+        source.parentFile.mkdirs()
+        // A Java constant can be inlined into cached Kotlin consumers from an older base.
+        source.setText("package ${namespace}.patchrelay;\npublic final class PatchRelayBuild { public static final String HOST_SHA256 = new String(\"$host\"); }\n", 'UTF-8')
+        new File(output, 'baseline-screen.js').bytes = bytes
+        new File(output, 'contract.json').setText(JsonOutput.toJson([
+            format:3, appId:appId, baseVersion:runtime.baseVersion, screenApi:runtime.screenApi,
+            screenIds:runtime.screenIds, hostSha256:host, nativeFiles:nativeFiles,
+            screenFiles:screenFiles, functionContract:Contract.read(Contract.inside(root, options.functionContractFile)), programSha256:Contract.hash(bytes)
+        ]), 'UTF-8')
+    }
+}
+
+abstract class RecordBaseline extends DefaultTask {
+    @Internal Map options
+    @Internal def prepared
+    @Internal def artifactProvider
+    @Internal def artifactsLoader
+    @Internal String artifactType
+    @Internal String variantName
+
+    private void result(File destination, File artifact) {
+        File pointer = project.layout.buildDirectory.file("outputs/patchrelay/$variantName/$artifactType-record.json").get().asFile
+        pointer.parentFile.mkdirs()
+        pointer.setText(JsonOutput.toJson([
+            baselineFile:project.rootDir.toPath().relativize(new File(destination, 'baseline.json').toPath()).toString().replace('\\','/'),
+            artifactFile:project.rootDir.toPath().relativize(artifact.toPath()).toString().replace('\\','/')
+        ]) + '\n', 'UTF-8')
+    }
+
+    @TaskAction void record() {
+        File root = project.rootDir
+        File preparedDir = prepared.get().outputDirectory.get().asFile
+        Map baseline = Contract.read(new File(preparedDir, 'contract.json'))
+        Map runtime = Contract.read(Contract.inside(root, options.runtimeFile))
+        if (Contract.fingerprint(root, runtime.nativeInputs, runtime.textExtensions) != baseline.nativeFiles ||
+            Contract.fingerprint(root, options.screenInputs, runtime.textExtensions) != baseline.screenFiles) {
+            throw new GradleException('Sources changed during the build; no PatchRelay baseline recorded')
+        }
+        File artifact
+        if (artifactType == 'apk') {
+            def built = artifactsLoader.load(artifactProvider.get())
+            if (built == null || built.applicationId != baseline.appId || built.elements.size() != 1) throw new GradleException('PatchRelay currently requires one non-split APK per variant')
+            artifact = new File(built.elements.first().outputFile)
+        } else artifact = artifactProvider.get().asFile
+        String entryName = (artifactType == 'aab' ? 'base/' : '') + 'assets/baseline-screen.js'
+        new ZipFile(artifact).withCloseable { zip ->
+            def entry = zip.getEntry(entryName)
+            if (entry == null || entry.size < 1 || entry.size > 2 * 1024 * 1024) throw new GradleException('Built artifact has no supported bundled screen program')
+            byte[] embedded = zip.getInputStream(entry).withCloseable { it.readNBytes(2 * 1024 * 1024 + 1) }
+            if (Contract.hash(embedded) != baseline.programSha256) throw new GradleException('Built artifact contains a different screen program; baseline rejected')
+        }
+        String artifactHash = Contract.fileHash(artifact)
+        File destination = Contract.inside(root, ".patchrelay/releases/baselines/${baseline.appId}/$variantName/$artifactType-$artifactHash")
+        File existing = new File(destination, 'baseline.json')
+        if (existing.isFile()) {
+            Map saved = Contract.read(existing)
+            if (saved.artifactSha256 != artifactHash || saved.nativeFiles != baseline.nativeFiles || saved.screenFiles != baseline.screenFiles ||
+                !new File(destination, 'baseline-sources.zip').isFile() ||
+                Contract.fileHash(new File(destination, 'baseline-sources.zip')) != saved.sourcesSha256 ||
+                Contract.fileHash(new File(destination, "screen-base.$artifactType")) != artifactHash ||
+                Contract.hash(new File(destination, 'baseline-screen.js').bytes) != baseline.programSha256) {
+                throw new GradleException('Existing PatchRelay record differs or is damaged; restore it rather than overwriting')
+            }
+            logger.lifecycle("PatchRelay baseline already recorded: $destination")
+            result(destination, artifact)
+            return
+        }
+        if (destination.exists()) throw new GradleException('Incomplete PatchRelay output exists; preserve it and choose a fresh build')
+        destination.mkdirs()
+        Files.copy(artifact.toPath(), new File(destination, "screen-base.$artifactType").toPath())
+        new File(destination, 'baseline-screen.js').bytes = new File(preparedDir, 'baseline-screen.js').bytes
+        File archive = new File(destination, 'baseline-sources.zip')
+        new ZipOutputStream(new FileOutputStream(archive)).withCloseable { zip ->
+            (baseline.nativeFiles.keySet() + baseline.screenFiles.keySet()).toSorted().unique().each { String path ->
+                if (path.split('/').any { it in ['.keys', '.env', 'local.properties'] } || path ==~ /(?i).*\.(key|pem|p12|jks|keystore)$/) throw new GradleException('Private credentials cannot be baseline inputs')
+                File file = Contract.inside(root, path)
+                def entry = new ZipEntry(path); entry.time = 0
+                zip.putNextEntry(entry); file.withInputStream { it.transferTo(zip) }; zip.closeEntry()
+            }
+        }
+        baseline.artifactType = artifactType
+        baseline.artifactSha256 = artifactHash
+        baseline[artifactType == 'apk' ? 'apkSha256' : 'aabSha256'] = artifactHash
+        baseline.variant = variantName
+        baseline.sourcesSha256 = Contract.fileHash(archive)
+        Files.writeString(existing.toPath(), JsonOutput.prettyPrint(JsonOutput.toJson(baseline)) + '\n', java.nio.file.StandardOpenOption.CREATE_NEW)
+        result(destination, artifact)
+        logger.lifecycle("PatchRelay baseline recorded: $destination\nBack up the entire directory privately; patch selection remains explicit.")
+    }
+}
+
+class PatchRelayPlugin implements Plugin<Project> {
+    void apply(Project project) {
+        def extension = project.extensions.create('patchrelayBaseline', BaselineOptions, project)
+        project.plugins.withId('com.android.application') {
+            project.extensions.getByName('androidComponents').onVariants(
+                project.extensions.getByName('androidComponents').selector().withBuildType('release')) { variant ->
+                def options = extension.values()
+                String cap = variant.name.capitalize()
+                def prepare = project.tasks.register("preparePatchRelay$cap", PrepareBaseline) {
+                    it.options = options; it.namespaceValue = variant.namespace; it.applicationId = variant.applicationId
+                    outputDirectory.set(project.layout.buildDirectory.dir("generated/patchrelay/${variant.name}"))
+                    dependsOn(options.compileTasks)
+                    outputs.upToDateWhen { false }
+                    notCompatibleWithConfigurationCache('PatchRelay snapshots declared project sources at execution time')
+                }
+                variant.sources.java.addGeneratedSourceDirectory(prepare, { it.outputDirectory })
+                project.tasks.matching { it.name == "compile${cap}Kotlin" }.configureEach {
+                    dependsOn(prepare)
+                    inputs.dir(prepare.flatMap { it.outputDirectory })
+                }
+                variant.buildConfigFields.put('HOST_SHA256', project.providers.provider {
+                    new BuildConfigField('String', "${variant.namespace.get()}.patchrelay.PatchRelayBuild.HOST_SHA256", null)
+                })
+                project.tasks.matching { it.name == "merge${cap}Assets" || it.name == "generate${cap}BuildConfig" }.configureEach { dependsOn(prepare) }
+                ['apk','aab'].each { type ->
+                    String buildName = type == 'apk' ? "assemble$cap" : "bundle$cap"
+                    def provider = variant.artifacts.get(type == 'apk' ? SingleArtifact.APK.INSTANCE : SingleArtifact.BUNDLE.INSTANCE)
+                    def record = project.tasks.register("recordPatchRelay${cap}${type.toUpperCase()}", RecordBaseline) {
+                        it.options = options; it.prepared = prepare; artifactProvider = provider
+                        artifactsLoader = variant.artifacts.getBuiltArtifactsLoader()
+                        artifactType = type; variantName = variant.name
+                        dependsOn(prepare, provider)
+                        notCompatibleWithConfigurationCache('PatchRelay writes immutable release records outside build/')
+                        onlyIf {
+                            def build = project.tasks.findByName(buildName)
+                            build != null && build.state.executed && build.state.failure == null
+                        }
+                    }
+                    project.tasks.matching { it.name == buildName }.configureEach { build ->
+                        build.finalizedBy(record)
+                    }
+                }
+            }
+        }
+    }
+}
+
+class BaselineOptions {
+    final Project project
+    String runtimeFile = 'runtime.json'
+    String programFile = 'screens/build/compileSync/js/main/productionExecutable/kotlin/PatchRelayScreens.js'
+    String baselineAsset
+    String functionContractFile = 'screens/build/generated/patchrelay/functions.json'
+    List<String> screenInputs = ['screens/src/commonMain']
+    List<String> compileTasks = [':screens:jvmTest', ':screens:compileProductionExecutableKotlinJs']
+    BaselineOptions(Project project) { this.project = project; baselineAsset = project.rootDir.toPath().relativize(new File(project.projectDir, 'src/main/assets/baseline-screen.js').toPath()).toString().replace('\\','/') }
+    Map values() { [functionContractFile:functionContractFile, runtimeFile:runtimeFile, programFile:programFile, baselineAsset:baselineAsset, screenInputs:screenInputs, compileTasks:compileTasks] }
+}