feat(version): sidecar and /api/client/version carry name, code and channel

The client compares names while Android installs by versionCode, and the
wire had no way to close that gap: the sidecar was one positional line and
the endpoint returned a name only. This is the plumbing that makes the
ordering key decidable by the client at all.

The sidecar is now JSON rather than a grown positional string. That shape
was chosen against a specific failure: the obvious growth path was
"<name> <code>", which a first-space split silently mangles the moment a
third field appears — the code stops parsing as an integer and the reader
falls back to name comparison WITHOUT erroring. JSON cannot mistake a new
field for an old one.

code is a POINTER on both sides, and omitempty on the wire. Absent has to
stay distinguishable from zero: a build published before ordering keys were
recorded genuinely has no code, and zero would claim it is infinitely old
rather than unknown.

A malformed sidecar now fails loudly instead of serving a blank version.
If an unreadable file produced an empty name, every client would compare
against nothing, conclude it was current, and go quiet — "I cannot read
this" and "there is nothing newer" would return the same answer, which is
the failure mode nobody reports because nobody is offered anything to
report.

The non-tag :latest path no longer RECONSTRUCTS the bundled APK's version.
android-release now publishes the sidecar as a release asset beside the
APK, and the image build downloads it. The old reconstruction duplicated a
derivation formula across two files, and could only ever recover the name —
the ordering key is build-time minutes and exists nowhere once that build
ends. Releases predating the sidecar report their name with a null code,
which is the honest answer rather than a guessed one.

image-release also drops to a shallow checkout: it needed full history and
tags only to re-derive versions from the tagged commit, and now touches git
for nothing. MINSTREL_VERSION comes from GITHUB_REF.

Two things checked rather than assumed. The Android Json sets
ignoreUnknownKeys, so the added fields cannot break already-installed apps.
It also sets coerceInputValues, which will silently turn a null code into 0
if step 4 declares the field non-nullable — recorded on task #3811, because
reading the field declaration alone would never reveal it.

Also fixes a stale comment block describing "the Flutter client", deleted
in v2026.08.18.

Step 3 of 5 — Scribe task #3810, milestone #390.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH

.gitea/workflows/release.yml

@@ -39,10 +39,9 @@ name: release
 # :latest (not just tags), a main build with no APK would silently strip
 # the in-app update channel off :latest until the next release. So on
 # non-tag builds image-release pulls the MOST RECENT release's signed APK
-# and reconstructs its exact versionName from the tagged commit's timestamp
-# (the same derivation android-release bakes in) for the version sidecar —
-# no rebuild, just rebundle. Tag builds keep bundling their own
-# freshly-built APK.
+# AND the version sidecar published beside it — the recorded values, not
+# recomputed ones — so no rebuild is needed, just a rebundle. Tag builds
+# keep bundling their own freshly-built APK.
 #
 # Android testing (lint + detekt + unit tests, debug APK upload on main)
 # lives in android.yml and runs independently on every push.
@@ -227,6 +226,8 @@ jobs:
         shell: bash
         env:
           CI_TOKEN: ${{ secrets.CI_TOKEN }}
+          VERSION_NAME: ${{ steps.ver.outputs.name }}
+          VERSION_CODE: ${{ steps.ver.outputs.code }}
         run: |
           set -euxo pipefail
           TAG="${GITHUB_REF#refs/tags/}"
@@ -234,6 +235,20 @@ jobs:
           APK_PATH="app/build/outputs/apk/release/app-release.apk"
           ls -lh "${APK_PATH}"
 
+          # Publish the version sidecar as a release asset next to the APK.
+          #
+          # This is what lets a later :latest build stop RECONSTRUCTING the
+          # bundled APK's version and simply read what was recorded. The
+          # ordering key in particular cannot be re-derived after the fact —
+          # it is build-time minutes, so once this job ends the value exists
+          # nowhere else. Reconstruction could only ever recover the name,
+          # and only by duplicating a formula that then has to be kept in
+          # step across two files.
+          SIDECAR_PATH="/tmp/minstrel.apk.version"
+          printf '{"name":"%s","code":%s,"channel":"stable"}\n' \
+            "${VERSION_NAME}" "${VERSION_CODE}" > "${SIDECAR_PATH}"
+          cat "${SIDECAR_PATH}"
+
           RELEASE_JSON="$(curl -fsSL \
             -H "Authorization: token ${CI_TOKEN}" \
             "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/tags/${TAG}")"
@@ -255,6 +270,20 @@ jobs:
             exit 1
           fi
 
+          # Same treatment for the sidecar. Named `.apk.version` so the
+          # downloader's `\.apk$` match cannot pick it up by mistake.
+          SIDECAR_HTTP=$(curl -sS -L -o /tmp/upload-sidecar.out -w '%{http_code}' \
+            -H "Authorization: token ${CI_TOKEN}" \
+            -F "attachment=@${SIDECAR_PATH}" \
+            "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets?name=minstrel-${TAG}.apk.version")
+          echo "sidecar_upload_http=${SIDECAR_HTTP}"
+          cat /tmp/upload-sidecar.out || true
+          echo
+          if [ "${SIDECAR_HTTP}" -lt 200 ] || [ "${SIDECAR_HTTP}" -ge 300 ]; then
+            echo "::error::version sidecar upload returned HTTP ${SIDECAR_HTTP}"
+            exit 1
+          fi
+
   image-release:
     name: Build + push container image
     # `needs:` waits for android-release. For tag pushes android-release
@@ -275,12 +304,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          # Full history + tags so non-tag :latest builds can resolve the
-          # latest release tag's commit and reconstruct the bundled APK's
-          # exact versionName from its timestamp (see "Bundle latest release
-          # APK" below).
-          fetch-depth: 0
-          fetch-tags: true
+          # Shallow is fine here. This job used to need full history + tags to
+          # re-derive the bundled APK's version from the tagged commit; it now
+          # downloads the sidecar the release recorded, and touches git for
+          # nothing. MINSTREL_VERSION comes from GITHUB_REF, not from git.
+          fetch-depth: 1
 
       - name: Detect buildable project
         id: guard
@@ -346,29 +374,30 @@ jobs:
         if: steps.guard.outputs.ready == 'true' && startsWith(github.ref, 'refs/tags/v')
         shell: bash
         env:
-          # Pulled from android-release.outputs.version_name so the
-          # sidecar string the server hands clients matches the
-          # versionName baked into the APK they're comparing against.
+          # Both pulled from android-release's outputs so the sidecar the
+          # server hands clients matches exactly what is baked into the APK
+          # they are comparing against.
           APK_VERSION_NAME: ${{ needs.android-release.outputs.version_name }}
+          APK_VERSION_CODE: ${{ needs.android-release.outputs.version_code }}
         run: |
           set -euxo pipefail
           # The artifact lands as `app-release.apk` (the original Gradle
           # output name). The Dockerfile COPYs client/* into /app/client/
           # and the server reads minstrel.apk + minstrel.apk.version.
           mv client/app-release.apk client/minstrel.apk
-          echo "${APK_VERSION_NAME}" > client/minstrel.apk.version
+          printf '{"name":"%s","code":%s,"channel":"stable"}\n' \
+            "${APK_VERSION_NAME}" "${APK_VERSION_CODE}" > client/minstrel.apk.version
+          cat client/minstrel.apk.version
           ls -lh client/
 
       - name: Bundle latest release APK (non-tag :latest builds)
         # Main pushes don't build an APK, but they DO move :latest — so
         # without this the in-app update channel would vanish from :latest
         # until the next tag. Pull the most-recent release's signed APK and
-        # reconstruct its exact versionName from the tagged commit's
-        # timestamp — the same derivation android-release uses — so the
-        # version sidecar the server hands clients matches the installed
-        # build.
+        # the sidecar published beside it, so what the server reports is what
+        # that build actually recorded rather than something re-derived here.
         # Degrades to an empty client/ (404 update channel) — never a wrong
-        # version — if no release / APK asset / tag-count can be resolved.
+        # version — if no release or APK asset can be resolved.
         if: steps.guard.outputs.ready == 'true' && !startsWith(github.ref, 'refs/tags/v')
         shell: bash
         env:
@@ -386,23 +415,28 @@ jobs:
           if [ -z "${TAG}" ] || [ -z "${APK_URL}" ]; then
             echo "::notice::latest release '${TAG:-?}' has no APK asset — image ships without bundled APK"; exit 0
           fi
-          # Reconstruct the bundled APK's name with the SAME derivation
-          # android-release uses — commit timestamp of the tagged commit. The
-          # two must agree exactly: this string is what the server hands
-          # clients to compare against what is installed, so a mismatch here
-          # is an update offered forever or never offered at all.
-          #
-          # This duplication is temporary. Once the tag itself becomes
-          # `v<version-name>`, this whole block collapses to `${TAG#v}` with
-          # nothing to recompute and nothing to keep in step.
-          COMMIT_TS="$(git log --format=%ct -1 "${TAG}" 2>/dev/null || true)"
-          if [ -z "${COMMIT_TS}" ]; then
-            echo "::notice::could not resolve commit timestamp for ${TAG} (tag not fetched?) — skipping APK bundle"; exit 0
-          fi
-          VERSION_NAME="$(date -u -d "@${COMMIT_TS}" +%Y.%m.%d.%H%M)"
           curl -fsSL -H "Authorization: token ${CI_TOKEN}" -o client/minstrel.apk "${APK_URL}"
-          echo "${VERSION_NAME}" > client/minstrel.apk.version
-          echo "::notice::bundled release APK ${TAG} as version ${VERSION_NAME}"
+
+          # Take the version the release RECORDED rather than recomputing it.
+          # This used to re-derive the name from the tagged commit, which meant
+          # the formula lived in two files that had to be kept in step, and it
+          # could only ever recover the name — the ordering key is build-time
+          # minutes and does not exist anywhere after that build ends.
+          SIDECAR_URL="$(printf '%s' "${REL_JSON}" | grep -oP '"browser_download_url":\s*"\K[^"]+' | grep -E '\.apk\.version$' | head -1)"
+          if [ -n "${SIDECAR_URL}" ]; then
+            curl -fsSL -H "Authorization: token ${CI_TOKEN}" -o client/minstrel.apk.version "${SIDECAR_URL}"
+            cat client/minstrel.apk.version
+          else
+            # Releases published before sidecars were attached. Their name is
+            # still recoverable from the tag, but their ordering key genuinely
+            # is not — so it is reported ABSENT rather than guessed. A wrong
+            # key is an install the platform refuses; an absent one just tells
+            # the client to fall back to comparing names, which is exactly
+            # what those builds already do.
+            echo "::notice::release ${TAG} predates the version sidecar — bundling with name only, no ordering key"
+            printf '{"name":"%s","code":null,"channel":"stable"}\n' "${TAG#v}" > client/minstrel.apk.version
+          fi
+          echo "::notice::bundled release APK from ${TAG}"
           ls -lh client/
 
       - name: Build and push