chore!: forward-merge v4.2-dev into v4.3-dev

.claude/skills/pr-description/SKILL.md

@@ -13,7 +13,8 @@ Generate a pull request title and description for the current branch using the p
 1. Determine the base branch:
    - Use the argument if provided
    - Otherwise, auto-detect: `git remote set-head origin --auto >/dev/null 2>&1 && git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/||'`
-   - Fall back to `v4.0-dev` if the command above fails
+   - If that fails, use the repository's default branch on GitHub: `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`
+   - If both fail, ask the user rather than guessing a version branch
 
 2. Gather context by running these git commands:
    - `git log --oneline $(git merge-base HEAD <base>)..HEAD` — all commits on this branch
@@ -25,19 +26,30 @@ Generate a pull request title and description for the current branch using the p
    - What specific code changes were made
    - Whether there are breaking changes
    - What tests were added or modified
+   - What value the change adds, and for whom
+   - What could go wrong: consensus impact, behaviour users could notice, slow or flaky tests
 
 4. Output a suggested PR title using conventional commits format:
-   - Scopes: `sdk`, `drive`, `dpp`, `dapi`, `dashmate`, `wasm-dpp`, `wasm-sdk`, `platform`
-   - Types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `build`
+   - Types and scopes: use only the `types:` and `scopes:` lists in `.github/workflows/pr.yml`. The PR title check rejects anything else, so read them from that file rather than from memory
+   - The scope is optional: leave it out (e.g. `chore: ...`) when the change spans several packages or no listed scope fits. Never invent a scope
+   - The subject must not start with an uppercase letter
    - Add `!` after the type for breaking changes (e.g. `feat!:`)
    - Format: **Suggested title:** `type(scope): description`
 
-5. Fill in this PR template (preserve all HTML comments exactly as shown):
+5. Fill in this PR template (preserve all HTML comments exactly as shown). The `## Basic explanation` section always comes first; the sections after it follow `.github/PULL_REQUEST_TEMPLATE.md`. If that file differs from the copy below, follow the file:
 
 ```markdown
 <!--- Provide a general summary of your changes in the Title above -->
 <!--- Pull request titles must use the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) format -->
 
+## Basic explanation
+
+**What this does:** <The change in the most basic terms, for a reader who does not know this code. Explain any jargon in passing, or avoid it.>
+
+**Value:** <What gets better and for whom (users, wallets, node operators, the network). Give a number when there is one.>
+
+**Risks:** <What could go wrong, sized honestly: say "Low" and why when it is low. Mention consensus impact, behaviour users could notice, and slow or flaky tests.>
+
 ## Issue being fixed or feature implemented
 <!--- Why is this change required? What problem does it solve? -->
 <!--- If it fixes an open issue, please link to the issue here. -->
@@ -69,6 +81,7 @@ Generate a pull request title and description for the current branch using the p
 - [ ] I have added or updated relevant unit/integration/functional/e2e tests
 - [ ] I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
 - [ ] I have made corresponding changes to the documentation if needed
+- [ ] If I added or changed GroveDB structure, I described it in the area's `structure.rs`, regenerated `grovedb-structure.json`, and checked the structure viewer link posted on this pull request
 
 **For repository code-owners and collaborators only**
 - [ ] I have assigned this pull request to a milestone
@@ -80,6 +93,7 @@ Output the entire PR description (title + body) as a single raw Markdown code bl
 
 ## Guidelines
 
+- Always open with `## Basic explanation`: three short paragraphs (what it does, value, risks) that someone outside this code can follow. For a security fix, keep it neutral: describe what the fix does, not how the bug could be exploited
 - Keep the description **concise** — avoid walls of text. Prefer short bullet points over paragraphs
 - Be specific — reference file paths, struct/function names, and types
 - For "How Has This Been Tested?", check `git diff` for new `*test*`, `*spec*` files. Briefly describe what tests cover (1 line per test file), not every individual test case

.editorconfig

@@ -11,6 +11,10 @@ end_of_line = lf
 [*.rs]
 indent_size = 4
 
+# Swift and Kotlin follow their languages' 4-space convention.
+[*.{swift,kt,kts}]
+indent_size = 4
+
 # Preserve the existing indentation of the Swift SDK Python scripts.
 [packages/swift-sdk/scripts/*.py]
 indent_size = 4

.github/NPM_RUNNER.md

@@ -0,0 +1,103 @@
+# NPM release runners
+
+NPM release compilation uses a fresh single-job runner with a unique
+`platform-release-<run-id>-<attempt>-npm` label in the `platform-release-builds`
+runner group. Kotlin releases use the same lifecycle with a `-kotlin` label. Publishing
+continues on GitHub-hosted Ubuntu with OIDC; the builder receives no publishing
+credentials. The `npm-release-build` action is shared by releases and image
+validation so both compile and pack with the same setup.
+
+## Image contract
+
+`.github/runner-requirements.json` pins the complete Linux image requirements and
+recipe commit. The job runs `ci-image-contract verify` before compiling. The
+runner must have `/opt/client-codegen` matching `packages/dapi-grpc/codegen.json`.
+Its protobuf 3.18.1 compiler is intentionally separate from Rust's protoc 32.0.
+TypeScript generation comes from the workspace's pinned `ts-protoc-gen` dependency.
+
+Image-owned native dependencies are verified, never installed using sudo. Rust,
+Node and the pinned WASM tools use writable runner/user locations. Cargo targets
+remain in job-local HOME; each release starts with fresh runner, HOME and workspace state. The
+runner needs no Docker CLI/socket or KVM device.
+
+## Provisioning and promotion
+
+Use the reviewed `dashpay/dash-selfhosted-image` recipe and a tested immutable
+image digest, not a moving tag. Deploy the host-side disposable release controller
+only after the NPM validation workflow succeeds on that image. Do not add generic
+release labels to persistent CI registrations. See the
+[controller installation and cleanup runbook](https://github.com/dashpay/dash-selfhosted-image/blob/main/docs/disposable-releases.md).
+Old release tags
+still contain their original workflows and do not automatically gain this fix.
+
+Requirements-changing PRs select a candidate label bound to the complete PR head
+and image digest. The image controller must support the `npm` job kind and
+`.github/workflows/npm-runner-validation.yml`. Manifests requesting native client
+generation require successful Rust, Kotlin and NPM candidate jobs for promotion;
+skipped fork jobs do not qualify. Existing same-repository/trusted-fork guards
+remain in effect.
+
+The trusted `runner-image-candidate.yml` bootstrap, controller and Rust/Kotlin
+candidate routing must be installed on each consuming branch before candidate
+promotion can work. Platform PRs #4702 and #4912 establish those pieces; reconcile
+their requirements/selector files with this NPM extension when landing them. In
+particular, update both the bootstrap's reusable-workflow SHA and its
+`control_revision` to a reviewed image-repository revision supporting
+`client_codegen` and `npm`. Merely changing `recipe_revision` is insufficient.
+The default `v4.2-dev` and `v4.3-dev` branches must each use an explicit compatible
+manifest; this change does not alter an existing release tag or deploy a runner.
+
+## Verification
+
+`npm-runner-validation.yml` runs the real release build and packing action, DAPI
+unit tests, and a byte-for-byte check that packed Node/web clients match the
+freshly generated files. It uploads tarballs but never publishes them.
+`test-client-codegen.yml` also builds the native compilers on hosted Linux/macOS,
+checks committed generated output, tests failure recovery and validates packing.
+
+Local setup and generator test commands are in `packages/dapi-grpc/README.md`.
+
+After installing the controller, use the `release.yml` dispatch with
+`tag=npm-test:v<package.json version>` on a protected development branch for a non-publishing
+NPM build. For Kotlin, dispatch `release-kotlin-sdk.yml` from the protected branch
+with an existing published `tag` and `dry_run=true`: compilation/artifact upload
+run, but release attachment and Maven publication are both skipped. Check that
+the image contract matches the selected source. Neither controller unit tests
+nor an image smoke test establishes that these end-to-end jobs pass.
+
+## Separate PR and release state
+
+The `platform-release-builds` organization runner group selects only
+`dashpay/platform` and contains only controller-created one-job registrations.
+Each build requests:
+
+```yaml
+runs-on:
+  group: platform-release-builds
+  labels: [self-hosted, Linux, X64, 'platform-release-${{ github.run_id }}-${{ github.run_attempt }}-npm']
+```
+
+There is no fallback to `npm-build`, `rust-ci` or `kotlin-ci`. Without the
+controller, builds stay queued. Runtime markers reject accidental routing to an
+ordinary runner; they are not cryptographic attestation. The host controller
+independently checks repository, event, workflow, run, attempt and commit before
+creating fresh JIT capacity. Only one job can consume each registration; the host
+destroys its container/processes, HOME, registration and workspace afterward.
+
+**Ordinary PR caching is unchanged.** PR validation keeps its own persistent
+Cargo/Gradle/Yarn caches. Releases reuse the prebaked image/toolchains but never
+mount PR state or restore shared executable dependency caches. Yarn caching is
+opted out only for the release runtime; Kotlin release build/publication disable
+Gradle cache restores. A cold release compile is the intentional tradeoff; do not
+reintroduce shared caches to speed it up without reviewing their writer trust.
+
+`release.yml` calls its local reusable workflow, so the workflow travels with the
+release source. Port it and the matching image requirements to 4.3; the host
+controller needs no branch-specific allowlist. Branch protection, trusted tags,
+fork approvals and hosted publishing authorization remain necessary. Optional
+selected-workflow group restrictions are defense in depth, not the mechanism
+that erases prior-job state. Labels alone are not authorization.
+
+This assumes a trusted host and pinned image. A fresh container does not repair
+host compromise or retroactively secure old release tags/artifacts. Merge/deploy
+the controller before relying on this workflow change for a release.

.github/ORDINARY_RUNNER_IMAGES.md

@@ -0,0 +1,37 @@
+# Coexisting ordinary AMD64 runner images
+
+The selector retains the existing generic ordinary labels only for the exact
+already-provisioned AMD64 contract `d272d01bcf3dfa620bbab1e9f31c3e1987862d33ec876bbad83c80f29de41a58`.
+For any different AMD64 manifest (including a recipe-only change), branch pushes
+and PRs that do not change that manifest require Linux/X64 plus:
+
+`platform-image-manifest-<canonical-full-manifest-sha256>-<rust|kotlin|npm>`
+
+This is an ordinary pool label, not a candidate label or an admission token.
+Runtime `ci-image-contract verify` remains mandatory. PRs changing AMD64
+requirements still need the exact current-head published candidate and its
+unchanged trust gates. Explicit ARM64 validation and its provisioning contract
+remain unchanged; new AMD64 ordinary contracts deliberately use X64 capacity.
+
+## Safe rollout order
+
+1. Keep legacy runner registrations/images/labels available for older branches
+   and existing PR heads. Do not overwrite an active runner or change its image.
+2. Obtain the exact published immutable new image from a successful trusted
+   publication. Verify manifest/recipe/provenance, confinement and applicable
+   compiler/KVM checks before creating separate capacity with fresh registration
+   and work volumes. Preserve the existing repository/group scope and resource
+   reserve/cleanup safeguards; do not copy Gateway credentials to the host.
+3. Give that new capacity only the corresponding versioned kind label, never
+   `rust-ci`, `kotlin-ci`, `npm-pr`, or any `platform-image-pr-*` candidate label.
+   Do not label an image merely because its tool versions look similar.
+4. Merge the selector repair normally before a new manifest becomes the branch
+   default. Verify actual candidate jobs and new ordinary capacity before merging
+   the recipe PR; source tests or a queued runner are not execution proof.
+5. Observe real ordinary exact-contract jobs and preserve old capacity until all
+   remaining consuming branches/heads are migrated or no longer need it. Rollback
+   must preserve both contracts; never relabel an incompatible image to clear CI.
+
+This source change does not create runners or register/alter any label, image,
+permission, workload, candidate allocator, or cleanup timer. Missing compatible
+new capacity intentionally queues work rather than selecting an old image.