@orbital_mcp/patchrelay 0.0.0-stage → 0.1.0-alpha04

package/LICENSE

@@ -0,0 +1,71 @@
+PatchRelay SDK License — Binary Use
+Version 1.0
+
+Copyright (c) 2026 the PatchRelay SDK copyright holders.
+All rights reserved except as expressly granted below.
+
+1. Scope
+
+This license applies to the PatchRelay Android SDK binaries and accompanying
+command-line tools and SDK documentation distributed with this notice (the "SDK"). It does not grant
+access to implementation source code or license separately identified third-party
+software. Third-party components remain governed by their respective licenses.
+
+2. Permission
+
+The copyright holders grant you a worldwide, non-exclusive, royalty-free license
+to use the SDK to develop, test and operate your own applications, including free
+and commercial applications, and to distribute the SDK as an integrated part of
+those applications. You may shrink, optimize, obfuscate and package the SDK as
+needed for that integration. You may keep copies in build caches and private
+dependency repositories for your development and deployment.
+
+Distribution of unmodified SDK releases through package registries or mirrors
+authorized by the copyright holders is permitted. This license and applicable
+third-party notices must accompany redistributed SDK copies; an application's
+legal-notices screen or bundled notices file is sufficient.
+
+Your application code and patches that you create remain yours. This license
+does not require you to disclose their source code.
+
+3. Restrictions
+
+You may not sell, sublicense or distribute the SDK as a standalone product,
+publish modified SDK releases, remove ownership or license notices, or represent
+the SDK as your own product without separate written permission. You may not
+reverse engineer, decompile or disassemble the SDK except to the extent that
+applicable law permits such activity despite this restriction. The permitted
+build transformations in section 2 are not prohibited by this section.
+
+No trademark rights or rights to implementation source code are granted.
+All rights not expressly granted are reserved.
+
+4. Application and update responsibility
+
+You are responsible for your applications, patches, signing keys, user disclosures,
+data handling and compliance with applicable laws and distribution-platform rules.
+Use of this SDK does not represent approval by Google Play or any other platform.
+
+5. Warranty and liability
+
+THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE COPYRIGHT HOLDERS ARE NOT
+LIABLE FOR CLAIMS, DAMAGES OR OTHER LIABILITY ARISING FROM THE SDK OR ITS USE,
+WHETHER IN CONTRACT, TORT OR OTHERWISE. THESE LIMITATIONS DO NOT EXCLUDE RIGHTS
+OR LIABILITY THAT APPLICABLE LAW DOES NOT ALLOW TO BE EXCLUDED.
+
+6. Termination
+
+These permissions terminate if you materially breach this license and do not
+remedy the breach within 30 days after receiving written notice from a copyright
+holder. On termination, stop using and distributing the SDK. Termination does not
+require end users to uninstall applications lawfully distributed before termination.
+
+7. Other terms
+
+This is a proprietary binary-use license, not an open-source license. No support,
+maintenance, future release or compatibility commitment is included. Changes to
+license terms for later SDK versions do not change the terms supplied with a
+previously received version. If a provision is unenforceable, the remaining
+provisions continue to apply to the extent permitted by law.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# PatchRelay CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An installable `patchrelay` command. No Python installation or Python commands.
+Uses Node 22+ and the project's Gradle wrapper with JDK 17 and Android SDK 35.
+
+Experimental alpha package: `@orbital_mcp/patchrelay`. The Android SDK is a
+separate Maven dependency; installing it does not install this CLI.
+
+## Install a built package
+
+```sh
+npm install --global /path/to/orbital_mcp-patchrelay-0.1.0-alpha04.tgz
+patchrelay --help
+```
+
+Public alpha installation:
+
+```sh
+npm install --global @orbital_mcp/patchrelay@alpha
+```
+
+Package page: https://www.npmjs.com/package/@orbital_mcp/patchrelay.
+The `alpha` tag identifies an experimental release rather than a stable one.
+
+Publisher setup requires `npm login`, verification that the account controls the
+`@orbital_mcp` scope, and `npm publish --access public --tag alpha` from the CLI
+package. Never paste npm credentials into this repository or an app. Ownership
+and authentication must be established before advertising a working public link.
+
+## Use
+
+Run inside your prepared Android project:
+
+```sh
+patchrelay init
+patchrelay baseline
+# Edit patchable screen Kotlin.
+patchrelay patch
+patchrelay catalog
+```
+
+`init` asks for module names, GitHub hosting repository (or HTTPS hosting) and
+signing-key location, stable signed-catalog HTTPS URL and channel. It writes
+`patchrelay.config.json` without key contents and appends catalog URL/channel
+settings to `local.properties`, preserving existing SDK path settings.
+It also copies the Gradle build plugin and prints the one-time settings/app plugin
+hooks. Apply those hooks so normal `assembleRelease` and `bundleRelease` builds
+automatically preserve matching baseline records; no extra baseline command is
+then required. This repository's demo already has the hooks. The plugin remains
+limited to prepared screen modules, not arbitrary Kotlin screen rewriting.
+It adds `.patchrelay/` and `.keys/` to Git ignore rules without removing existing
+rules. Custom signing-key locations still need their own ignore protection.
+It does not generate/rotate keys, install SDK hooks, migrate ordinary native
+screens or configure private-host authentication. Review generated JS/APK/
+BuildConfig paths before building. A custom Kotlin/JS export name or Gradle
+variant needs corresponding settings changes.
+
+`baseline` asks for a unique record name, builds/tests the configured screen
+module, bundles its program, builds the APK, checks the native fingerprint and
+saves APK, program, compatibility JSON and private source ZIP under
+`.patchrelay/releases/baselines/NAME`. It changes the configured bundled JS asset
+as part of preparing that native build. Back up the entire baseline directory
+privately. Local output is not cloud backup. Do not publish the source ZIP.
+
+`patch` lists available baseline paths and asks you to choose one explicitly,
+then asks for a positive patch version. It never selects a record automatically.
+It rejects native/contract changes and altered source archives, compiles/tests
+the full current supported screen program and signs `screens.js` plus `patch.json`.
+Output directories are exclusive; prior releases are never overwritten.
+
+GitHub artifact URLs use the configured repository and the convention
+`patch-ROUTE_HASH-VERSION`; the route hash binds app ID, base version and exact
+native fingerprint, avoiding collisions between apps/builds. `--tag` overrides
+that release tag. For another HTTPS host,
+the command asks for the actual final `screens.js` URL. Nothing is uploaded and
+no hosted catalog is changed by these commands. The app's catalog endpoint is
+configured separately in its native build; it is not the JS artifact URL.
+
+Patch outputs are under `.patchrelay/releases/patches/ROUTE_HASH/VERSION`.
+A locked, local version record under `.patchrelay/versions` prevents reusing or
+lowering a version for the same exact base even with a different output folder.
+A failed write after reservation consumes that version; choose a higher one.
+Back up these records. They cannot detect versions published from another
+machine unless you retain the latest published records/catalog. All channels
+for an exact base share the version sequence.
+
+## Stable update discovery
+
+`patchrelay catalog` asks for a signed patch manifest, the existing signed catalog
+(or explicit `new` for the first one), channel and final manifest HTTPS URL.
+It verifies signatures/artifact hashes, preserves routes for older bases and
+updates only that patch's exact app/base route. It rejects a route downgrade,
+wrong app/channel, ambiguous routes and more than 64 supported base builds.
+It writes a new signed `catalog.json` locally, never overwriting hosted data.
+
+Use one stable catalog URL per app/channel. Different apps can share one GitHub
+repository while using separate catalogs, signing keys and immutable patch
+releases. Upload/verify `screens.js` and its `patch.json` first, then replace
+the hosted catalog. Keep every artifact still referenced by an older base.
+GitHub asset replacement is not atomic; a brief failed check must leave the
+current app working. Private-source hosting still needs accessible HTTPS patch
+delivery or a separate authenticated gateway; GitHub credentials aren't embedded.
+
+The prepared host calls `updates.stageCatalog(catalogUrl, channel)` off the UI
+thread. The SDK verifies the catalog, selects the exact installed fingerprint,
+then verifies the selected manifest and downloads only the latest complete
+program. No match means no update. Existing version/signature checks still apply.
+This supports skipping intermediate patches, not arbitrary data migrations.
+The new demo checks once per process after healthy first rendering, silently;
+the downloaded patch activates on a later process start, not mid-session.
+
+Automation can supply explicit values:
+
+```sh
+patchrelay baseline --name android-v1
+patchrelay patch --baseline .patchrelay/releases/baselines/android-v1/baseline.json --version 1
+```
+
+There is no default signing key material and no default publisher repository.
+The configured `publicKeyFile` must contain the Base64 DER public key pinned in
+the app; signing refuses a mismatched private key. The key file format is the existing PatchRelay Base64 DER PKCS#8 RSA private key
+(minimum 3072 bits). Keep it out of Git and releases. The CLI signs locally;
+private keys are never sent to Maven, npm or the patch host.
+
+Normal Gradle baselines are stored at
+`.patchrelay/releases/baselines/APP_ID/VARIANT/apk-ARTIFACT_HASH/` or
+`aab-ARTIFACT_HASH/`. Select the desired `baseline.json` explicitly in `patch`.
+Both formats work for patch compilation; AAB files themselves are not installed
+by this tool. `patchrelay baseline` remains useful for a developer-named APK record.
+
+## Recover a lost record
+
+```sh
+patchrelay baseline --from YOUR-COMMIT
+```
+
+You supply the record name and original APK when asked. Recovery checks out only
+that explicitly supplied revision into a detached worktree, using its project
+settings when present or the current module-layout settings otherwise. It uses
+the selected revision's runtime contract and sources. Current branch/edits remain
+untouched. The rebuilt APK must match the original APK hash exactly. Different
+signing/toolchain output is rejected; without a matching release, ship a new base.
+Recovery worktrees and build diagnostics stay under `.patchrelay/recovery/`.
+
+## Project contract
+
+This CLI is independent of this repository's Python tools, but it is **not an
+automatic integration plugin for arbitrary Android apps**. Projects still need:
+
+- Prepared Kotlin/JS screens and explicit native hooks.
+- `runtime.json` format 1 / screen API 2 with app/base/screen identity, declared
+  native inputs and text-normalization extensions.
+- Gradle generation of `HOST_SHA256`, `BASE_VERSION` and `APPLICATION_ID` in the
+  configured BuildConfig, following the existing sorted SHA-256 contract.
+- An Android host using the SDK and configured trust keys/update endpoint.
+
+The CLI does not scan ordinary Kotlin to discover patchable methods. Multiple
+app/variant projects need separately reviewed configuration and release records.
+Baseline selection remains manual. Signed catalog authoring/routing is implemented;
+automatic remote uploads and arbitrary app integration are still pending.
+
+## Build this CLI from source
+
+```sh
+cd cli
+npm test
+npm pack
+```
+
+The npm tarball contains CLI runtime files, the Gradle build-plugin source,
+documentation and license: no Android SDK/app implementation, signing keys,
+baseline archives or private R8 mappings.
+The CLI is JavaScript distributed to developers, so its runtime is inspectable.
+Android SDK AAR obfuscation is a separate build step, not protection for CLI code.

package/bin/patchrelay.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/main.mjs';
+
+main().catch(error => {
+  console.error(`PatchRelay: ${error.message}`);
+  process.exitCode = 1;
+});

package/gradle-plugin/build.gradle

@@ -0,0 +1,15 @@
+plugins { id 'groovy'; id 'java-gradle-plugin' }
+repositories { google(); mavenCentral() }
+dependencies {
+    implementation localGroovy()
+    compileOnly 'com.android.tools.build:gradle-api:8.6.0'
+}
+java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }
+gradlePlugin {
+    plugins {
+        baseline {
+            id = 'dev.patchrelay.baseline'
+            implementationClass = 'dev.patchrelay.gradle.PatchRelayPlugin'
+        }
+    }
+}

package/gradle-plugin/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'patchrelay-gradle-plugin'

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

@@ -0,0 +1,220 @@
+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()
+        source.setText("package ${namespace}.patchrelay;\npublic final class PatchRelayBuild { public static final String HOST_SHA256 = \"$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, 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 })
+                variant.buildConfigFields.put('HOST_SHA256', project.providers.provider {
+                    new BuildConfigField('String', "${variant.namespace.get()}.patchrelay.PatchRelayBuild.HOST_SHA256", null)
+                })
+                project.tasks.matching { it.name in ["merge${cap}Assets", "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
+    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() { [runtimeFile:runtimeFile, programFile:programFile, baselineAsset:baselineAsset, screenInputs:screenInputs, compileTasks:compileTasks] }
+}

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@orbital_mcp/patchrelay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha04",
+  "description": "Build and sign patches for prepared PatchRelay Android projects",
+  "type": "module",
+  "bin": { "patchrelay": "bin/patchrelay.mjs" },
+  "engines": { "node": ">=22" },
+  "files": ["bin/", "src/", "README.md", "LICENSE", "gradle-plugin/build.gradle", "gradle-plugin/settings.gradle", "gradle-plugin/src/main/"],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepack": "node scripts/package.mjs"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": { "access": "public", "tag": "alpha" }
+}

package/src/main.mjs

@@ -0,0 +1,279 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, cpSync, renameSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { sha256, readJson, hostHash, inside, fingerprint, checkNative, emptyOutput, command, jdkTool, gradle, loadBaseline, signedManifest, routeId, reserveVersion, verifiedEnvelope, updateCatalog, signPayload, validateUrl, baselineFiles } from './project.mjs';
+
+const configName = 'patchrelay.config.json';
+const help = `PatchRelay — build and sign patches for prepared Android projects
+
+  patchrelay init                 Configure this project once
+  patchrelay baseline             Build and save a named base release
+  patchrelay patch                Select a baseline, build and sign a patch
+  patchrelay catalog              Update a signed app/channel catalog locally
+  patchrelay baseline --from REF  Recover an explicitly selected old release
+
+Options: --name NAME, --baseline PATH, --version NUMBER, --url HTTPS_URL,
+         --tag TAG, --out PATH, --from REF, --apk PATH
+Catalog options: --patch PATH, --catalog PATH_OR_new, --channel NAME, --url MANIFEST_URL
+
+No automatic baseline selection. No uploads. No Python required.
+Requires Node 22+, JDK 17, Android SDK and a prepared PatchRelay screen module.`;
+
+function argumentsFor(args) {
+  const [action = 'help', ...rest] = args;
+  const options = {};
+  const allowed = { init: [], baseline: ['name', 'out', 'from', 'apk'], patch: ['baseline', 'version', 'url', 'tag', 'out'],
+    catalog: ['patch', 'catalog', 'channel', 'url', 'out'] };
+  if (['help', '--help', '-h', '--version'].includes(action)) return { action, options };
+  if (!allowed[action]) throw new Error(`Unknown command: ${action}. Run patchrelay --help.`);
+  if (rest.includes('--help')) return { action: 'help', options };
+  for (let i = 0; i < rest.length; i += 2) {
+    const key = rest[i].replace(/^--/, '');
+    if (!rest[i].startsWith('--') || !allowed[action].includes(key) || !rest[i + 1] || rest[i + 1].startsWith('--') || Object.hasOwn(options, key)) {
+      throw new Error(`Invalid option: ${rest[i]}. Run patchrelay --help.`);
+    }
+    options[key] = rest[i + 1];
+  }
+  if (options.apk && !options.from) throw new Error('--apk requires an explicit --from revision.');
+  return { action, options };
+}
+
+function findRoot(start) {
+  let path = resolve(start);
+  while (true) {
+    if (existsSync(join(path, configName)) || existsSync(join(path, 'runtime.json'))) return path;
+    const parent = dirname(path);
+    if (parent === path) throw new Error('Run in a prepared Android project containing runtime.json. See the CLI integration guide.');
+    path = parent;
+  }
+}
+
+function name(value) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,119}$/.test(value)) throw new Error('Use a release name containing letters, numbers, dots, underscores or hyphens.');
+  return value;
+}
+
+function project(root, fallback) {
+  const settings = existsSync(join(root, configName)) ? readJson(join(root, configName)) : fallback;
+  if (!settings || settings.format !== 1) throw new Error('Run patchrelay init first.');
+  const runtime = readJson(inside(root, settings.runtimeFile));
+  if (runtime.format !== 1 || runtime.screenApi !== 2 || !Array.isArray(runtime.nativeInputs) || !Array.isArray(runtime.screenIds) || !runtime.screenIds.length) throw new Error('Unsupported project runtime contract.');
+  return { root, settings, runtime };
+}
+
+function nativeFiles(ctx) { return fingerprint(ctx.root, ctx.runtime.nativeInputs, ctx.runtime.textExtensions); }
+function screenFiles(ctx) { return fingerprint(ctx.root, ctx.settings.screenInputs, ctx.runtime.textExtensions); }
+function saveJson(file, data) { writeFileSync(file, JSON.stringify(data, null, 2) + '\n', { flag: 'wx' }); }
+
+export function verifyBuild(ctx, expected) {
+  const source = readFileSync(inside(ctx.root, ctx.settings.buildConfigFile), 'utf8');
+  for (const [field, value] of Object.entries({ HOST_SHA256: expected, APPLICATION_ID: ctx.runtime.appId, BASE_VERSION: ctx.runtime.baseVersion })) {
+    let text = source;
+    if (field === 'HOST_SHA256') {
+      const generated = source.match(/\bHOST_SHA256 = ([\w.]+\.PatchRelayBuild)\.HOST_SHA256;/);
+      if (generated) {
+        const [module, tail] = ctx.settings.buildConfigFile.replaceAll('\\', '/').split('/build/generated/source/buildConfig/');
+        const variant = tail?.split('/')[0];
+        if (!variant) throw new Error('Configure the standard generated BuildConfig path for Gradle baseline integration.');
+        text = readFileSync(inside(ctx.root, `${module}/build/generated/patchrelay/${variant}/${generated[1].replaceAll('.', '/')}.java`), 'utf8');
+      }
+    }
+    const match = text.match(new RegExp(`\\b${field} = ("(?:[^"\\\\]|\\\\.)*")`));
+    if (!match || JSON.parse(match[1]) !== value) throw new Error(`Built APK ${field} does not match the release contract. Check host Gradle integration.`);
+  }
+}
+
+function buildBaseline(ctx, out) {
+  const { root, settings, runtime } = ctx;
+  emptyOutput(out);
+  gradle(root, settings.compileTasks);
+  const program = readFileSync(inside(root, settings.programFile));
+  if (!program.length || program.length > 2 * 1024 * 1024) throw new Error('Compiled screen program must be 1 byte–2 MiB.');
+  new TextDecoder('utf-8', { fatal: true }).decode(program);
+  // The bundled program is a native-build input; include it before hashing/building.
+  copyFileSync(inside(root, settings.programFile), inside(root, settings.baselineAsset));
+  const before = nativeFiles(ctx);
+  const sources = screenFiles(ctx);
+  gradle(root, settings.baseTasks);
+  checkNative(before, nativeFiles(ctx));
+  checkNative(sources, screenFiles(ctx));
+  verifyBuild(ctx, hostHash(before));
+  const apk = readFileSync(inside(root, settings.apkFile));
+  writeFileSync(join(out, 'screen-base.apk'), apk, { flag: 'wx' });
+  writeFileSync(join(out, 'baseline-screen.js'), program, { flag: 'wx' });
+  const staging = inside(root, `.patchrelay/work/${randomUUID()}/sources`);
+  mkdirSync(staging, { recursive: true });
+  for (const path of [...new Set([...Object.keys(before), ...Object.keys(sources)])]) {
+    if (path.split('/').some(part => ['.keys', 'local.properties', '.env'].includes(part)) || /\.(key|pem|p12|jks|keystore)$/i.test(path) ||
+        resolve(root, path) === resolve(root, settings.signingKey)) throw new Error('A private credential file is declared as a baseline input. Remove it from native/screen inputs.');
+    const target = inside(staging, path);
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(inside(root, path), target);
+  }
+  checkNative(before, fingerprint(staging, Object.keys(before), runtime.textExtensions));
+  checkNative(sources, fingerprint(staging, Object.keys(sources), runtime.textExtensions));
+  const archive = join(out, 'baseline-sources.zip');
+  command(root, jdkTool('jar'), ['--create', '--file', archive, '-C', staging, '.']);
+  const baseline = { format: 3, appId: runtime.appId, baseVersion: runtime.baseVersion, screenApi: runtime.screenApi,
+    hostSha256: hostHash(before), screenIds: runtime.screenIds, nativeFiles: before, screenFiles: sources,
+    apkSha256: sha256(apk), programSha256: sha256(program), sourcesSha256: sha256(readFileSync(archive)) };
+  saveJson(join(out, 'baseline.json'), baseline);
+  return baseline;
+}
+
+async function init(root, ask) {
+  if (existsSync(join(root, configName))) throw new Error('Project is already configured. Edit patchrelay.config.json to change settings.');
+  const runtime = readJson(join(root, 'runtime.json'));
+  const app = await ask('Android app module', existsSync(join(root, 'demo')) ? 'demo' : 'app');
+  const screens = await ask('Prepared Kotlin screen module', 'screens');
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(app) || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(screens)) throw new Error('Use simple Gradle module names.');
+  const repository = await ask('Patch GitHub repository (owner/repo), or "https" for another host');
+  if (repository !== 'https' && !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) throw new Error('Use owner/repo, or https.');
+  const signingKey = await ask('Private signing-key file location (not key contents)', '.keys/patch-signing.key');
+  const catalogUrl = validateUrl(await ask('Stable HTTPS URL for this app\'s signed catalog'));
+  const channel = await ask('Update channel', 'production');
+  if (!/^[a-z][a-z0-9_-]{0,31}$/.test(channel)) throw new Error('Use a lowercase channel name.');
+  const settings = { format: 1, runtimeFile: 'runtime.json', repository: repository === 'https' ? null : repository, signingKey,
+    publicKeyFile: `${app}/patch-public-key.txt`,
+    screenInputs: [`${screens}/src/commonMain`], compileTasks: [`:${screens}:jvmTest`, `:${screens}:compileProductionExecutableKotlinJs`],
+    baseTasks: [`:${app}:assembleRelease`], programFile: `${screens}/build/compileSync/js/main/productionExecutable/kotlin/${screens === 'screens' ? 'PatchRelayScreens' : screens}.js`,
+    baselineAsset: `${app}/src/main/assets/baseline-screen.js`, apkFile: `${app}/build/outputs/apk/release/${app}-release.apk`,
+    buildConfigFile: `${app}/build/generated/source/buildConfig/release/${runtime.appId.replaceAll('.', '/')}/BuildConfig.java`,
+    outputDir: '.patchrelay/releases' };
+  const pluginSource = existsSync(fileURLToPath(new URL('../gradle-plugin/build.gradle', import.meta.url)))
+    ? fileURLToPath(new URL('../gradle-plugin/', import.meta.url))
+    : fileURLToPath(new URL('../../gradle-plugin/', import.meta.url));
+  const pluginClass = 'src/main/groovy/dev/patchrelay/gradle/PatchRelayPlugin.groovy';
+  const pluginFolder = existsSync(join(root, 'gradle-plugin', pluginClass)) ? 'gradle-plugin' : 'patchrelay-gradle-plugin';
+  if (existsSync(join(root, pluginFolder)) && !existsSync(join(root, pluginFolder, pluginClass))) {
+    throw new Error('Plugin destination already contains unrelated files. Preserve them and choose a clean integration directory.');
+  }
+  if (!existsSync(join(root, pluginFolder))) cpSync(pluginSource, join(root, pluginFolder), {
+    recursive: true, errorOnExist: true, force: false,
+    filter: path => !path.endsWith('/build') && !path.endsWith('\\build') && !path.endsWith('/.gradle') && !path.endsWith('\\.gradle')
+  });
+  if (Array.isArray(runtime.nativeInputs)) {
+    for (const path of [`${pluginFolder}/src/main`, `${pluginFolder}/build.gradle`, `${pluginFolder}/settings.gradle`]) {
+      if (!runtime.nativeInputs.includes(path)) runtime.nativeInputs.push(path);
+    }
+    writeFileSync(join(root, 'runtime.json'), JSON.stringify(runtime, null, 2) + '\n');
+  }
+  saveJson(join(root, configName), settings);
+  const ignoreFile = join(root, '.gitignore');
+  let ignored = existsSync(ignoreFile) ? readFileSync(ignoreFile, 'utf8') : '';
+  for (const rule of ['.patchrelay/', '.keys/', 'local.properties']) {
+    if (!ignored.split(/\r?\n/).includes(rule)) ignored += `${ignored.endsWith('\n') || !ignored ? '' : '\n'}${rule}\n`;
+  }
+  writeFileSync(ignoreFile, ignored);
+  const localFile = join(root, 'local.properties');
+  const local = existsSync(localFile) ? readFileSync(localFile, 'utf8') : '';
+  writeFileSync(localFile, local + (local.endsWith('\n') || !local ? '' : '\n') + `patchrelay.catalogUrl=${catalogUrl}\npatchrelay.channel=${channel}\n`);
+  console.log('Saved patchrelay.config.json. Review module paths before building. Keep private keys and .patchrelay/ out of Git.');
+  console.log(`Gradle hook: add includeBuild("${pluginFolder}") inside settings pluginManagement, and id("dev.patchrelay.baseline") in the app plugins block. Commit the plugin sources/config with your native release.`);
+}
+
+async function recover(ctx, ref, original, out) {
+  if (!ref || ref.startsWith('-')) throw new Error('Choose an explicit commit, tag or branch.');
+  const expected = sha256(readFileSync(original));
+  const commit = command(ctx.root, 'git', ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`], true);
+  const work = inside(ctx.root, `.patchrelay/recovery/${randomUUID()}`);
+  mkdirSync(work, { recursive: true });
+  const checkout = join(work, 'checkout');
+  command(ctx.root, 'git', ['worktree', 'add', '--detach', checkout, commit]);
+  console.log(`Recovery checkout: ${checkout}`);
+  const candidate = join(work, 'candidate');
+  const baseline = buildBaseline(project(checkout, ctx.settings), candidate);
+  if (baseline.apkSha256 !== expected) {
+    const file = join(candidate, 'baseline.json');
+    // Failed candidates must not look like accepted release records.
+    renameSync(file, join(candidate, 'unverified-baseline.json'));
+    throw new Error('Rebuilt APK differs from the supplied original APK. Recovery rejected; current checkout is unchanged.');
+  }
+  baseline.recoveredFromCommit = commit;
+  writeFileSync(join(candidate, 'baseline.json'), JSON.stringify(baseline, null, 2) + '\n');
+  emptyOutput(out);
+  cpSync(candidate, out, { recursive: true, force: false, errorOnExist: true });
+}
+
+export async function main(args = process.argv.slice(2), cwd = process.cwd(), input) {
+  const { action, options } = argumentsFor(args);
+  if (action === '--version') { console.log('0.1.0-alpha04'); return; }
+  if (['help', '--help', '-h'].includes(action)) { console.log(help); return; }
+  let terminal;
+  const ask = input || (async (question, fallback) => {
+    if (!process.stdin.isTTY) throw new Error(`Missing value: ${question}. Supply flags or run in an interactive terminal.`);
+    terminal ??= createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await terminal.question(`${question}${fallback ? ` [${fallback}]` : ''}: `)).trim() || fallback;
+    if (!answer) throw new Error(`${question} is required.`);
+    return answer;
+  });
+  try {
+    const root = findRoot(cwd);
+    if (action === 'init') { await init(root, ask); return; }
+    const ctx = project(root);
+    if (action === 'baseline') {
+      const release = name(options.name || await ask('New baseline record name'));
+      const out = options.out ? resolve(root, options.out) : inside(root, `${ctx.settings.outputDir}/baselines/${release}`);
+      if (existsSync(out)) throw new Error('Output exists. Choose a new baseline name or output directory.');
+      if (options.from) {
+        const apk = resolve(root, options.apk || await ask('Original released APK file'));
+        await recover(ctx, options.from, apk, out);
+      } else buildBaseline(ctx, out);
+      console.log(`Baseline saved: ${out}\nBack up this entire directory privately.`);
+    } else if (action === 'catalog') {
+      const publicKey = readFileSync(inside(root, ctx.settings.publicKeyFile));
+      const patchFile = resolve(root, options.patch || await ask('Signed patch.json file path'));
+      const manifest = verifiedEnvelope(readFileSync(patchFile), publicKey);
+      if (manifest.appId !== ctx.runtime.appId) throw new Error('Selected patch belongs to another app.');
+      const bytes = readFileSync(join(dirname(patchFile), 'screens.js'));
+      if (sha256(bytes) !== manifest.sha256) throw new Error('Patch artifact does not match its signed manifest.');
+      const previousFile = options.catalog || await ask('Existing signed catalog path, or "new" for the first catalog');
+      const previous = previousFile === 'new' ? null : verifiedEnvelope(readFileSync(resolve(root, previousFile)), publicKey);
+      const channel = options.channel || await ask('Channel', 'production');
+      const url = validateUrl(options.url || await ask('Final HTTPS URL of this patch.json'));
+      const catalog = updateCatalog(previous, manifest, url, channel);
+      const envelope = signPayload(catalog, readFileSync(resolve(root, ctx.settings.signingKey)), publicKey);
+      const out = options.out ? resolve(root, options.out) : inside(root, `${ctx.settings.outputDir}/catalogs/${randomUUID()}`);
+      emptyOutput(out);
+      saveJson(join(out, 'catalog.json'), envelope);
+      console.log(`Signed catalog saved: ${join(out, 'catalog.json')}\nApp: ${catalog.appId}; channel: ${channel}; base builds: ${catalog.entries.length}\nNothing uploaded. Serve this catalog at the app's stable catalog URL after uploading its patch files.`);
+    } else {
+      const baselineDir = inside(root, `${ctx.settings.outputDir}/baselines`);
+      if (!options.baseline && existsSync(baselineDir)) {
+        console.log('Available records (choose explicitly):\n' + baselineFiles(baselineDir).map(file => `  ${file}`).join('\n'));
+      }
+      const file = resolve(root, options.baseline || await ask('Baseline JSON file path'));
+      const baseline = loadBaseline(file);
+      if (baseline.appId !== ctx.runtime.appId || baseline.baseVersion !== ctx.runtime.baseVersion || baseline.screenApi !== ctx.runtime.screenApi ||
+          JSON.stringify(baseline.screenIds) !== JSON.stringify(ctx.runtime.screenIds)) throw new Error('Selected baseline belongs to a different app/base/screen contract.');
+      const currentNative = nativeFiles(ctx);
+      checkNative(baseline.nativeFiles, currentNative);
+      const currentScreens = screenFiles(ctx);
+      const changed = [...new Set([...Object.keys(currentScreens), ...Object.keys(baseline.screenFiles)])].filter(path => currentScreens[path] !== baseline.screenFiles[path]);
+      if (!changed.length) throw new Error('No supported screen changes found.');
+      console.log('Changed screen inputs:\n' + changed.map(path => `  ${path}`).join('\n'));
+      const version = Number(options.version || await ask('Patch version (positive integer)'));
+      if (!Number.isSafeInteger(version) || version <= 0) throw new Error('Patch version must be a positive safe integer.');
+      const route = routeId(baseline);
+      const tag = name(options.tag || `patch-${route.slice(0, 24)}-${version}`);
+      const url = options.url || (ctx.settings.repository ? `https://github.com/${ctx.settings.repository}/releases/download/${tag}/screens.js` : await ask('Final HTTPS URL for screens.js'));
+      const out = options.out ? resolve(root, options.out) : inside(root, `${ctx.settings.outputDir}/patches/${route}/${version}`);
+      emptyOutput(out);
+      gradle(root, ctx.settings.compileTasks);
+      checkNative(currentNative, nativeFiles(ctx));
+      checkNative(currentScreens, screenFiles(ctx));
+      const bytes = readFileSync(inside(root, ctx.settings.programFile));
+      if (sha256(bytes) === baseline.programSha256) throw new Error('Compiled program is unchanged.');
+      if (!ctx.settings.publicKeyFile) throw new Error('Configure publicKeyFile to match the key pinned in your app.');
+      const envelope = signedManifest(baseline, version, url, bytes, readFileSync(resolve(root, ctx.settings.signingKey)),
+        readFileSync(inside(root, ctx.settings.publicKeyFile)));
+      reserveVersion(root, baseline, version, () => {
+        writeFileSync(join(out, 'screens.js'), bytes, { flag: 'wx' });
+        saveJson(join(out, 'patch.json'), envelope);
+      });
+      console.log(`Signed patch saved: ${out}\nNothing uploaded. Target release tag: ${tag}`);
+    }
+  } finally { terminal?.close(); }
+}

package/src/project.mjs

@@ -0,0 +1,174 @@
+import { createHash, createPrivateKey, createPublicKey, constants, sign, verify } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, realpathSync, lstatSync, mkdirSync, openSync, closeSync, unlinkSync, writeFileSync, renameSync } from 'node:fs';
+import { resolve, relative, dirname, isAbsolute, basename, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+export const readJson = file => JSON.parse(readFileSync(file, 'utf8'));
+export function baselineFiles(folder) {
+  if (!existsSync(folder)) return [];
+  return readdirSync(folder, { withFileTypes: true }).flatMap(entry => {
+    const path = inside(folder, entry.name);
+    if (entry.isSymbolicLink()) return [];
+    if (entry.isDirectory()) return baselineFiles(path);
+    return entry.isFile() && entry.name === 'baseline.json' ? [path] : [];
+  }).sort();
+}
+export const routeId = value => sha256(JSON.stringify([value.appId, value.baseVersion, value.hostSha256]));
+// Match Python's existing sorted, ASCII-escaped JSON contract, including Unicode paths.
+export const hostHash = files => sha256(JSON.stringify(Object.fromEntries(Object.entries(files)
+  .sort(([a], [b]) => Buffer.compare(Buffer.from(a), Buffer.from(b)))))
+  .replace(/[\u007f-\uffff]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`));
+
+export function inside(root, path) {
+  const full = resolve(root, path);
+  const child = relative(resolve(root), full);
+  if (child === '..' || child.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(child)) {
+    throw new Error('Project path escapes the project directory.');
+  }
+  if (existsSync(full) && realpathSync(full) !== full) {
+    const actual = relative(realpathSync(root), realpathSync(full));
+    if (actual === '..' || actual.startsWith('..\\') || actual.startsWith('../') || isAbsolute(actual)) throw new Error('Project symlink escapes the project directory.');
+  }
+  return full;
+}
+
+export function fingerprint(root, paths, extensions) {
+  const result = {};
+  function visit(file) {
+    inside(root, relative(root, file));
+    const info = lstatSync(file);
+    if (info.isSymbolicLink()) throw new Error('Declare real source paths, not symbolic links.');
+    if (info.isDirectory()) {
+      for (const name of readdirSync(file).sort()) visit(join(file, name));
+    } else if (info.isFile()) {
+      let data = readFileSync(file);
+      if (extensions.some(suffix => basename(file).endsWith(suffix))) data = Buffer.from(data.toString('utf8').replaceAll('\r\n', '\n'));
+      result[relative(root, file).replaceAll('\\', '/')] = sha256(data);
+    }
+  }
+  for (const path of paths) visit(inside(root, path));
+  return Object.fromEntries(Object.entries(result).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+}
+
+export function checkNative(before, after) {
+  const changed = [...new Set([...Object.keys(before), ...Object.keys(after)])].filter(name => before[name] !== after[name]);
+  if (changed.length) throw new Error(`Native inputs changed; build a new base: ${changed.slice(0, 10).join(', ')}`);
+}
+
+export function emptyOutput(path) {
+  mkdirSync(dirname(path), { recursive: true });
+  mkdirSync(path); // Exclusive: never overwrite an existing release directory.
+}
+
+export function command(root, executable, args, capture = false) {
+  const result = spawnSync(executable, args, { cwd: root, stdio: capture ? 'pipe' : 'inherit', encoding: 'utf8', shell: false });
+  if (result.error) throw new Error(`Cannot run ${executable}: ${result.error.message}`);
+  if (result.status !== 0) throw new Error(`${executable} failed (${result.status}).${capture ? ` ${result.stderr?.trim() || ''}` : ''}`);
+  return result.stdout?.trim();
+}
+
+export function jdkTool(name) {
+  const binary = process.platform === 'win32' ? `${name}.exe` : name;
+  return process.env.JAVA_HOME ? join(process.env.JAVA_HOME, 'bin', binary) : binary;
+}
+
+export function gradle(root, tasks) {
+  command(root, jdkTool('java'), ['-classpath', inside(root, 'gradle/wrapper/gradle-wrapper.jar'),
+    'org.gradle.wrapper.GradleWrapperMain', ...tasks, '--console=plain', '--max-workers=2']);
+}
+
+export function loadBaseline(file) {
+  const baseline = readJson(file);
+  if (baseline.format !== 3 || !baseline.nativeFiles || !baseline.screenFiles || !Array.isArray(baseline.screenIds) ||
+      !baseline.screenIds.length || !/^[a-f0-9]{64}$/.test(baseline.hostSha256) ||
+      hostHash(baseline.nativeFiles) !== baseline.hostSha256) throw new Error('Invalid baseline compatibility record.');
+  if (baseline.sourcesSha256) {
+    const archive = join(dirname(file), 'baseline-sources.zip');
+    if (!existsSync(archive) || sha256(readFileSync(archive)) !== baseline.sourcesSha256) throw new Error('Baseline source archive is missing or altered.');
+  }
+  return baseline;
+}
+
+export function validateUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error('Use an absolute HTTPS artifact URL.'); }
+  if (url.protocol !== 'https:' || url.username || url.password || url.hash) throw new Error('Use HTTPS without URL credentials or a fragment.');
+  return url.href;
+}
+
+export function signedManifest(baseline, version, artifactUrl, bytes, keyBytes, publicKeyBytes) {
+  if (!Number.isSafeInteger(version) || version <= 0) throw new Error('Patch version must be a positive safe integer.');
+  if (!bytes.length || bytes.length > 2 * 1024 * 1024) throw new Error('Patch must be between 1 byte and 2 MiB.');
+  new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  return signPayload({ schema: 3, screenApi: baseline.screenApi, runtime: 'kotlin-screen-js',
+    hostSha256: baseline.hostSha256, appId: baseline.appId, baseVersion: baseline.baseVersion, version,
+    screenIds: baseline.screenIds, artifactUrl: validateUrl(artifactUrl), sha256: sha256(bytes) }, keyBytes, publicKeyBytes);
+}
+
+export function signPayload(value, keyBytes, publicKeyBytes) {
+  const key = createPrivateKey({ key: Buffer.from(keyBytes.toString().trim(), 'base64'), format: 'der', type: 'pkcs8' });
+  if (key.asymmetricKeyType !== 'rsa' || key.asymmetricKeyDetails.modulusLength < 3072) throw new Error('Use a PatchRelay RSA signing key of at least 3072 bits.');
+  if (publicKeyBytes && !createPublicKey(key).export({ format: 'der', type: 'spki' }).equals(Buffer.from(publicKeyBytes.toString().trim(), 'base64'))) {
+    throw new Error('Signing key does not match the configured app public key.');
+  }
+  const payload = Buffer.from(JSON.stringify(value));
+  const envelope = { payload: payload.toString('base64'), signature: sign('sha256', payload, { key, padding: constants.RSA_PKCS1_PADDING }).toString('base64') };
+  if (Buffer.byteLength(JSON.stringify(envelope)) > 64 * 1024) throw new Error('Signed metadata exceeds the SDK 64 KiB limit.');
+  return envelope;
+}
+
+export function verifiedEnvelope(bytes, publicKeyBytes) {
+  if (bytes.length > 64 * 1024) throw new Error('Signed metadata exceeds 64 KiB.');
+  const envelope = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+  if (typeof envelope.payload !== 'string' || typeof envelope.signature !== 'string') throw new Error('Invalid signed envelope.');
+  const payload = Buffer.from(envelope.payload, 'base64');
+  const key = createPublicKey({ key: Buffer.from(publicKeyBytes.toString().trim(), 'base64'), format: 'der', type: 'spki' });
+  if (!verify('sha256', payload, key, Buffer.from(envelope.signature, 'base64'))) throw new Error('Metadata signature is invalid.');
+  return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(payload));
+}
+
+export function updateCatalog(previous, manifest, manifestUrl, channel) {
+  if (!/^[a-z][a-z0-9_-]{0,31}$/.test(channel)) throw new Error('Use a lowercase channel name, e.g. production or beta.');
+  if (manifest.schema !== 3 || manifest.screenApi !== 2 || manifest.runtime !== 'kotlin-screen-js' || typeof manifest.appId !== 'string' ||
+      !manifest.appId || typeof manifest.baseVersion !== 'string' || !manifest.baseVersion || manifest.baseVersion.length > 128 ||
+      !/^[a-f0-9]{64}$/.test(manifest.hostSha256) || !Number.isSafeInteger(manifest.version) || manifest.version <= 0) throw new Error('Invalid patch route.');
+  const catalog = previous || { schema: 1, kind: 'patchrelay-catalog', appId: manifest.appId, channel, entries: [] };
+  if (catalog.schema !== 1 || catalog.kind !== 'patchrelay-catalog' || catalog.appId !== manifest.appId || catalog.channel !== channel ||
+      !Array.isArray(catalog.entries) || catalog.entries.length > 64) throw new Error('Existing catalog belongs to a different app/channel or is invalid.');
+  const seen = new Set();
+  for (const entry of catalog.entries) {
+    const route = JSON.stringify([entry.baseVersion, entry.hostSha256]);
+    if (typeof entry.baseVersion !== 'string' || !entry.baseVersion || entry.baseVersion.length > 128 || !/^[a-f0-9]{64}$/.test(entry.hostSha256) ||
+        !Number.isSafeInteger(entry.version) || entry.version <= 0 || seen.has(route)) throw new Error('Invalid or duplicate catalog route.');
+    validateUrl(entry.manifestUrl);
+    seen.add(route);
+  }
+  const old = catalog.entries.find(entry => entry.baseVersion === manifest.baseVersion && entry.hostSha256 === manifest.hostSha256);
+  if (old && manifest.version <= old.version) throw new Error('Catalog patch versions must increase for each exact base.');
+  const entries = catalog.entries.filter(entry => entry !== old);
+  entries.push({ baseVersion: manifest.baseVersion, hostSha256: manifest.hostSha256, version: manifest.version, manifestUrl: validateUrl(manifestUrl) });
+  if (entries.length > 64) throw new Error('Catalog has more than 64 base builds.');
+  return { schema: 1, kind: 'patchrelay-catalog', appId: manifest.appId, channel, entries };
+}
+
+export function reserveVersion(root, baseline, version, writePatch) {
+  const folder = inside(root, '.patchrelay/versions');
+  mkdirSync(folder, { recursive: true });
+  const file = join(folder, `${routeId(baseline)}.json`);
+  let lock;
+  try { lock = openSync(file + '.lock', 'wx'); }
+  catch { throw new Error('Version record is locked. Another patch build may be running; inspect stale locks before removing them.'); }
+  try {
+    if (existsSync(file)) {
+      const record = readJson(file);
+      if (record.format !== 1 || !Number.isSafeInteger(record.highest) || record.highest <= 0) throw new Error('Invalid local patch version record. Restore its backup.');
+      if (version <= record.highest) throw new Error(`Patch version must exceed ${record.highest} for this exact base.`);
+    }
+    const temporary = file + '.pending';
+    // Reserve before emitting files: a failed write consumes a version rather than reusing a signature identity.
+    writeFileSync(temporary, JSON.stringify({ format: 1, highest: version }) + '\n', { flag: 'wx', flush: true });
+    renameSync(temporary, file);
+    writePatch();
+  } finally { closeSync(lock); unlinkSync(file + '.lock'); }
+}