Runtime updates

runtime.json is the single source of truth for the tested runtime, prefix revision, build recipe, component versions, source revisions, URLs, and checksums. scripts/update_runtime.py pins a published Arknights macOS Runtime release. It changes runtime.json and every document that states the pin. The logic is in scripts/lib/runtime_update.py.

Wine and DXMT are one tested unit. Do not combine arbitrary latest versions. A runtime release never changes the client pin. Do not approve a runtime because its version is higher.

Update the pin#

1. Run just runtime update TAG. For example, just runtime update v0.7.0.
2. Read the changed files with git diff.
3. Run just check scripts.
4. Run just runtime to download, hash, extract, and validate the archive.
5. Test a fresh and an existing prefix through install or update, each client's web-login path where provided, game start, and clean exit.
6. Add or update prefix migrations when the runtime state contract requires them.

TAG is a release tag or latest. latest is the default. It selects the newest published release and skips drafts. It skips prereleases unless you add prerelease: just runtime update latest prerelease.

What the script reads#

The script reads three assets of the release over HTTPS. It does not download the runtime archive.

The script fails and writes nothing in these cases:

• A .sha256 file differs from provenance.json in name or checksum.
• provenance.json names another tag.
• The interface of the release differs from the interface block of runtime.json. The script never rewrites that block. Change the interface by hand and review the Swift runtime code.
• The MoltenVK commit changed. provenance.json has no MoltenVK version. Pass --moltenvk-version.

What the script rewrites#

A second run with the same tag changes nothing.

Manual steps#

Change these by hand when the release changes them.

• The libraries list of the runtimeRelease entry in docs/legal/licenses/index.json. Copy it from the runtime inventory of the release. Keep spdx, files, and note equal to the same inventory.
• The licenses of Wine, DXMT, and MoltenVK in the same file.
• The prose of the documents. For example, the statement that the runtime has no media stack.
• prefixRevision in runtime.json. Increase it when a runtime or prefix configuration change must reach existing installations. The archive checksum is part of the effective runtime revision, so a binary-only refresh replays the runtime migrations without a prefixRevision increase.
• The optional interface.runtimeCapabilities file name. It names a capability manifest at the runtime root that declares Hardware Cursor and MetalFX support. If the entry or manifest is missing or invalid, the client uses conservative defaults and sends no unsupported overrides.

Check the pin#

just runtime check runs scripts/update_runtime.py --check. just check scripts runs it too. The check fails when:

• runtime.name, runtime.url, buildRecipe.url, or provenance.buildRepository does not match the tag in the archive URL.
• A generated runtime block in a document differs from runtime.json.

Add a marker#

A marker pair surrounds a generated block. The generator replaces the lines between the two markers.

<!-- runtime:begin NAME -->
<!-- runtime:end NAME -->

1. Write a render function in scripts/lib/runtime_update.py. It takes runtime.json data and returns Markdown that ends with a newline.
2. Add the function to the dictionary in render_documents. The key is the document path. The value maps NAME to the function result.
3. Add the marker pair to the document. Use a lowercase NAME with hyphens.
4. Run just runtime update TAG with the current tag. Add a test to scripts/tests/test_update_runtime.py.

License automation owns the marker rules. The runtime blocks belong to this script.