gowalk-cicd 1.0.174 → 1.0.175

package/README.md

@@ -154,6 +154,20 @@ the mobile workflow. No hosting provider is assumed: consumers can deploy the
 artifact to their chosen host without granting this package an unrelated cloud
 account or domain.
 
+## Delivery timing and cache cost
+
+Keep routine push-to-verified-production delivery within about 2–5 minutes while preserving
+checks and coverage. [CI performance receipts](docs/CI_PERFORMANCE.md) distinguish runner time,
+queueing, retries and provider work. Count conditional dependency priming as auxiliary cost.
+
+Promoted candidates now seed missing default-branch SDK/pub/Flutter Pods/Gradle caches through
+verified key/path/compression identities and dependency-only work. They never promote PR cache
+bytes or duplicate a compile. Default-branch macOS fallbacks transfer the IPA and leave Apple
+processing to a required Linux verification job. Apple must positively confirm the exact upload,
+file, eligible build and app before delivery completes; its processing time remains external.
+The final complete upload receipt and verification proof are in `apple-verified-<run>-<attempt>`.
+See [candidate artifacts](docs/CANDIDATE_ARTIFACTS.md) and [cache behavior](docs/GRADLE_CACHE.md).
+
 ## iOS credentials
 
 Use encrypted repository secrets for both the App Store Connect API key and

package/action/action.yml

@@ -63,6 +63,10 @@ inputs:
     description: "Set to 'false' to stop after producing the IPA"
     required: false
     default: "true"
+  defer-provider-verification:
+    description: Transfer only; caller must verify the retained handoff on Linux before declaring delivery complete
+    required: false
+    default: "false"
   archive:
     description: >
       Set to 'false' to skip archive + export + upload entirely. Useful for
@@ -172,6 +176,20 @@ inputs:
     required: false
     default: "true"
 
+outputs:
+  verification-deferred:
+    description: A successful transfer still requires the caller's Linux verification
+    value: ${{ inputs.defer-provider-verification == 'true' && inputs.upload == 'true' && inputs.archive == 'true' }}
+  handoff-path:
+    description: Exact deferred handoff file which the caller must retain before Linux verification
+    value: ${{ steps.upload.outputs.handoff-path }}
+  handoff-sha256:
+    description: Exact handoff content digest
+    value: ${{ steps.upload.outputs.handoff-sha256 }}
+  handoff-producer-attempt:
+    description: Attempt that performed the binary transfer
+    value: ${{ steps.upload.outputs.handoff-producer-attempt }}
+
 runs:
   using: composite
   steps:
@@ -776,13 +794,21 @@ runs:
       shell: bash
       env:
         APP_STORE_APPLE_ID: ${{ inputs.app-store-apple-id || env.CFG_APP_STORE_APPLE_ID }}
+        DEFER_PROVIDER_VERIFICATION: ${{ inputs.defer-provider-verification }}
+        APPLE_UPLOAD_MANAGE_VERSION: ${{ inputs.manage-app-store-version }}
+        INPUT_WHATS_NEW: ${{ inputs.app-store-whats-new }}
+        APP_STORE_LOCALE: ${{ inputs.app-store-locale || env.CFG_LOCALE }}
       run: |
         IPA=$(ls "$RUNNER_TEMP"/export/*.ipa | head -1)
+        options=()
+        if [ "$DEFER_PROVIDER_VERIFICATION" = true ]; then
+          options+=(--transfer-only --handoff "$RUNNER_TEMP/apple-verification.json")
+        fi
         python3 "$SWIFT_APP_ACTION/scripts/upload_build.py" "$IPA" \
-          --report "$RUNNER_TEMP/apple-build-upload.json"
+          --report "$RUNNER_TEMP/apple-build-upload.json" "${options[@]}"
 
     - name: Record confirmed iOS upload
-      if: ${{ steps.upload.outcome == 'success' }}
+      if: ${{ steps.upload.outcome == 'success' && inputs.defer-provider-verification != 'true' }}
       shell: bash
       run: node "$SWIFT_APP_ACTION/scripts/mobile_release.cjs" finish-upload ios
 
@@ -800,13 +826,15 @@ runs:
     # continuation can resume or complete that same upload identity instead of
     # rebuilding different bytes under the number the receipt names.
     - name: Retain the exported IPA for upload recovery
-      if: ${{ always() && inputs.archive == 'true' && inputs.upload == 'true' && steps.upload.outcome != 'success' }}
+      if: ${{ always() && inputs.archive == 'true' && inputs.upload == 'true'
+            && (steps.upload.outcome != 'success' || inputs.defer-provider-verification == 'true') }}
       uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4
       env:
         NODE_OPTIONS: --require "${{ env.SWIFT_APP_ACTION }}/scripts/artifact_env.cjs"
       with:
         name: apple-ipa-${{ github.run_id }}-${{ github.run_attempt }}
         path: ${{ runner.temp }}/export/*.ipa
+        compression-level: 0 # An IPA is already a ZIP; avoid duplicate compression on the Mac.
         if-no-files-found: ignore
         retention-days: 7
 
@@ -818,6 +846,7 @@ runs:
     # TESTFLIGHT_ONLY decision): there is no editable version id to write to.
     - name: Set App Store "What's New"
       if: ${{ inputs.archive == 'true' && inputs.upload == 'true'
+            && inputs.defer-provider-verification != 'true'
             && inputs.manage-app-store-version == 'true'
             && env.STORE_VERSION_LOCKED == ''
             && (inputs.app-store-whats-new != '' || env.CFG_WHATS_NEW != '') }}

package/action/scripts/apple_upload_handoff.cjs

@@ -0,0 +1,103 @@
+/* Admit the exact successful transfer and handoff, never an arbitrary receipt or cache. */
+'use strict';
+const fs = require('node:fs');
+const {createHash} = require('node:crypto');
+const {join} = require('node:path');
+const github = require('./mobile_release_api.cjs');
+const SCHEMA = 'gowalk-cicd/apple-upload-handoff.v1';
+const positive = value => Number.isSafeInteger(value) && value > 0;
+const id = value => typeof value === 'string' && /^[A-Za-z0-9-]{1,64}$/.test(value);
+const fail = code => { throw Error(`apple_upload_verify_${code}`); };
+
+function read(path, digest, attempt, env = process.env) {
+  if (fs.statSync(path).size > 2 * 1024 * 1024) fail('handoff_size');
+  const bytes = fs.readFileSync(path);
+  if (bytes.length > 2 * 1024 * 1024 || !/^[a-f0-9]{64}$/.test(digest || '') ||
+      createHash('sha256').update(bytes).digest('hex') !== digest) fail('handoff_digest');
+  const value = JSON.parse(bytes), owner = value.owner || {}, r = value.receipt || {}, m = value.metadata || {};
+  const event = JSON.parse(fs.readFileSync(env.GITHUB_EVENT_PATH, 'utf8'));
+  if (value.schema !== SCHEMA || owner.repository !== env.GITHUB_REPOSITORY ||
+      !/^[\w.-]+\/[\w.-]+$/.test(owner.repository || '') || !/^[a-f0-9]{40}$/.test(owner.source_sha || '') ||
+      owner.source_sha !== env.GITHUB_SHA || owner.ref !== env.GITHUB_REF || !owner.ref?.startsWith('refs/heads/') ||
+      owner.ref !== `refs/heads/${event.repository?.default_branch}` ||
+      !['push', 'workflow_dispatch'].includes(owner.event) || owner.event !== env.GITHUB_EVENT_NAME ||
+      !positive(owner.run_id) || owner.run_id !== Number(env.GITHUB_RUN_ID) || !positive(owner.run_attempt) ||
+      !positive(attempt) || !positive(Number(env.GITHUB_RUN_ATTEMPT)) ||
+      owner.run_attempt !== attempt || attempt > Number(env.GITHUB_RUN_ATTEMPT) ||
+      !positive(owner.deployment_id) || owner.deployment_id !== Number(env.MOBILE_RELEASE_DEPLOYMENT_ID)) {
+    fail('handoff_owner');
+  }
+  if (r.schema !== 'gowalk-cicd/apple-build-upload-receipt.v1' || r.stage !== 'transferred' ||
+      !/^\d+$/.test(r.app_id || '') || !id(r.upload_id) || !id(r.file_id) ||
+      !/^[A-Za-z0-9.-]+$/.test(r.bundle_id || '') || !/^\d+$/.test(r.cfBundleVersion || '') ||
+      !/^\d+(\.\d+){0,2}$/.test(r.cfBundleShortVersionString || '') ||
+      !/^[a-f0-9]{64}$/.test(r.sha256 || '') || r.fileName !== `${r.sha256}.ipa` || !positive(r.fileSize)) {
+    fail('handoff_receipt');
+  }
+  if (typeof m.enabled !== 'boolean' || typeof m.only_if_empty !== 'boolean' ||
+      typeof m.notes !== 'string' || Buffer.byteLength(m.notes) > 1024 * 1024 || m.notes.includes('\0') ||
+      !/^[A-Za-z0-9-]{2,35}$/.test(m.locale || '') || m.enabled && !id(m.version_id)) fail('handoff_metadata');
+  return value;
+}
+
+function transferred(job) {
+  if (!Array.isArray(job.steps)) return false;
+  const selected = ['Build and transfer iOS binary', 'Retain Apple verification handoff'].map(name =>
+    job.steps.filter(step => step.name === name));
+  if (selected.some(steps => steps.length !== 1 || steps[0].status !== 'completed' ||
+      steps[0].conclusion !== 'success' || !positive(steps[0].number))) return false;
+  return selected[0][0].number < selected[1][0].number;
+}
+
+async function verifyProducer(value, artifactId, api = github) {
+  if (!positive(artifactId)) fail('artifact_identity');
+  const o = value.owner;
+  const run = await api.request('GET', `/actions/runs/${o.run_id}/attempts/${o.run_attempt}`);
+  if (run.id !== o.run_id || run.run_attempt !== o.run_attempt || run.head_sha !== o.source_sha ||
+      run.path !== '.github/workflows/deploy.yml' || run.event !== o.event ||
+      `refs/heads/${run.head_branch}` !== o.ref || run.repository?.full_name !== o.repository ||
+      run.head_repository?.full_name !== o.repository) fail('producer_run');
+  const result = await api.request('GET', `/actions/runs/${o.run_id}/attempts/${o.run_attempt}/jobs?per_page=100`);
+  if (!Array.isArray(result.jobs) || result.jobs.length >= 100) fail('producer_jobs');
+  const jobs = result.jobs.filter(job => job.name === 'iOS TestFlight' || job.name?.endsWith('/ iOS TestFlight'));
+  // A later symbol-retention failure does not undo these exact completed steps.
+  // The producer's original failure remains red; only Apple delivery is reconciled here.
+  if (jobs.length !== 1 || jobs[0].status !== 'completed' || !['success', 'failure'].includes(jobs[0].conclusion) ||
+      jobs[0].head_sha !== o.source_sha || !transferred(jobs[0])) fail('producer_job');
+  const artifact = await api.request('GET', `/actions/artifacts/${artifactId}`);
+  if (artifact.id !== artifactId || artifact.expired !== false || artifact.workflow_run?.id !== o.run_id ||
+      artifact.workflow_run?.head_sha !== o.source_sha ||
+      artifact.name !== `apple-verification-${o.run_id}-${o.run_attempt}`) fail('producer_artifact');
+}
+
+async function phase(value, api = github) {
+  const o = value.owner, record = await api.request('GET', `/deployments/${o.deployment_id}`);
+  const payload = record.payload || {};
+  if (record.id !== o.deployment_id || record.sha !== o.source_sha || record.task !== 'mobile-upload' ||
+      payload.schema !== 'gowalk-cicd/mobile-upload-owner.v1' || payload.platform !== 'ios' ||
+      !/^[a-f0-9]{64}$/.test(payload.fingerprint || '') ||
+      record.environment !== `mobile-ios-${payload.fingerprint}` || payload.run_id !== o.run_id ||
+      payload.source_sha !== o.source_sha || !positive(payload.run_attempt) ||
+      payload.run_attempt > o.run_attempt) fail('deployment_owner');
+  const rows = await api.request('GET', `/deployments/${o.deployment_id}/statuses?per_page=1`);
+  if (rows[0]?.state === 'success' && rows[0]?.description === 'uploaded') return 'uploaded';
+  if (rows[0]?.state !== 'in_progress' || rows[0]?.description !== 'uploading') fail('deployment_phase');
+  return 'uploading';
+}
+
+function metadata(value, env = process.env) {
+  if (!env.GITHUB_ENV) return;
+  const m = value.metadata;
+  if (!m.enabled) return fs.appendFileSync(env.GITHUB_ENV, 'APPLE_UPLOAD_METADATA_READY=false\n');
+  const notes = join(env.RUNNER_TEMP, 'verified-apple-whats-new.txt');
+  fs.writeFileSync(notes, m.notes, {mode: 0o600});
+  const fields = {APPLE_UPLOAD_METADATA_READY: 'true', APP_STORE_VERSION_ID: m.version_id,
+    MARKETING_VERSION: value.receipt.cfBundleShortVersionString, APP_STORE_WHATS_NEW_FILE: notes,
+    WHATS_NEW_ONLY_IF_EMPTY: String(m.only_if_empty), APP_STORE_LOCALE: m.locale};
+  for (const [name, content] of Object.entries(fields)) {
+    if (/[\r\n]/.test(content)) fail('metadata_environment');
+    fs.appendFileSync(env.GITHUB_ENV, `${name}=${content}\n`);
+  }
+}
+
+module.exports = {read, verifyProducer, phase, metadata, fail};

package/action/scripts/apple_upload_handoff.py

@@ -0,0 +1,65 @@
+"""Bind transferred IPA identity and metadata to one durable GitHub producer attempt."""
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+
+SCHEMA = "gowalk-cicd/apple-upload-handoff.v1"
+FIELDS = ("schema", "stage", "app_id", "bundle_id", "cfBundleVersion", "cfBundleShortVersionString",
+          "sha256", "fileName", "fileSize", "upload_id", "file_id")
+
+
+def positive(name):
+    value = os.environ.get(name, "")
+    if not re.fullmatch(r"[1-9][0-9]*", value) or int(value) > 2 ** 53 - 1:
+        raise ValueError("apple_handoff_owner_invalid")
+    return int(value)
+
+
+def metadata():
+    env = os.environ
+    managed = env.get("APPLE_UPLOAD_MANAGE_VERSION", "false")
+    if managed not in ("true", "false"):
+        raise ValueError("apple_handoff_metadata_invalid")
+    explicit = env.get("INPUT_WHATS_NEW", "")
+    notes = explicit or env.get("CFG_WHATS_NEW", "")
+    enabled = managed == "true" and not env.get("STORE_VERSION_LOCKED") and bool(notes)
+    if enabled and not explicit and env.get("CFG_WHATS_NEW_FILE"):
+        notes = Path(env["CFG_WHATS_NEW_FILE"]).read_text()
+    version = env.get("APP_STORE_VERSION_ID", "") if enabled else ""
+    locale = env.get("APP_STORE_LOCALE", "") or "en-US"
+    if (len(notes.encode()) > 1024 * 1024 or "\0" in notes or not re.fullmatch(r"[A-Za-z0-9-]{2,35}", locale)
+            or enabled and not re.fullmatch(r"[A-Za-z0-9-]{1,64}", version)):
+        raise ValueError("apple_handoff_metadata_invalid")
+    return {"enabled": enabled, "version_id": version, "locale": locale,
+            "only_if_empty": not bool(explicit), "notes": notes if enabled else ""}
+
+
+def prepare():
+    env = os.environ
+    repository, sha, ref = (env.get(name, "") for name in ("GITHUB_REPOSITORY", "GITHUB_SHA", "GITHUB_REF"))
+    event = env.get("GITHUB_EVENT_NAME", "")
+    context = json.loads(Path(env["GITHUB_EVENT_PATH"]).read_text())
+    if (event not in ("push", "workflow_dispatch") or not re.fullmatch(r"[\w.-]+/[\w.-]+", repository)
+            or not re.fullmatch(r"[a-f0-9]{40}", sha) or not ref.startswith("refs/heads/")
+            or ref != "refs/heads/" + context["repository"]["default_branch"]
+            or "\n" in ref or "\r" in ref or len(ref) > 300):
+        raise ValueError("apple_handoff_owner_invalid")
+    return {"schema": SCHEMA, "owner": {"repository": repository, "source_sha": sha, "ref": ref, "event": event,
+            "run_id": positive("GITHUB_RUN_ID"), "run_attempt": positive("GITHUB_RUN_ATTEMPT"),
+            "deployment_id": positive("MOBILE_RELEASE_DEPLOYMENT_ID")}, "metadata": metadata()}
+
+
+def write(path, handoff, receipt):
+    if receipt.get("stage") != "transferred" or "\n" in str(path) or "\r" in str(path):
+        raise ValueError("apple_handoff_transfer_unconfirmed")
+    handoff = {**handoff, "receipt": {name: receipt[name] for name in FIELDS}}
+    data = (json.dumps(handoff, sort_keys=True, separators=(",", ":")) + "\n").encode()
+    path.write_bytes(data)
+    digest = hashlib.sha256(data).hexdigest()
+    if output := os.environ.get("GITHUB_OUTPUT"):
+        with open(output, "a") as stream:
+            stream.write(f"handoff-path={path}\nhandoff-sha256={digest}\n")
+            stream.write(f"handoff-producer-attempt={handoff['owner']['run_attempt']}\n")
+    return digest

package/action/scripts/apple_upload_verify.cjs

@@ -0,0 +1,86 @@
+/* Linux verifies the already-transferred IPA; it never reserves, uploads or rebuilds anything. */
+'use strict';
+const fs = require('node:fs');
+const {parseArgs} = require('node:util');
+const {setTimeout: delay} = require('node:timers/promises');
+const github = require('./mobile_release_api.cjs');
+const apple = require('./reconcile_apple_upload.cjs');
+const handoff = require('./apple_upload_handoff.cjs');
+
+function credential(env = process.env) {
+  const pem = env.ASC_KEY_P8 || (env.ASC_KEY_PATH ? fs.readFileSync(env.ASC_KEY_PATH, 'utf8') : '');
+  if (!pem || !env.ASC_KEY_ID || !env.ASC_ISSUER_ID) handoff.fail('credential_missing');
+  return {pem, id: env.ASC_KEY_ID, issuer: env.ASC_ISSUER_ID};
+}
+
+async function observe(receipt, get) {
+  const path = `/buildUploads/${receipt.upload_id}?include=build`, response = await get(path);
+  const upload = response.data, attrs = upload?.attributes || {};
+  if (upload?.id !== receipt.upload_id || attrs.cfBundleVersion !== receipt.cfBundleVersion ||
+      attrs.cfBundleShortVersionString !== receipt.cfBundleShortVersionString) handoff.fail('upload_identity');
+  if (attrs.state?.state === 'FAILED') handoff.fail('processing_failed');
+  if (attrs.state?.state !== 'COMPLETE') return null;
+  const buildId = upload.relationships?.build?.data?.id;
+  if (!/^[A-Za-z0-9-]{1,64}$/.test(buildId || '')) handoff.fail('build_identity');
+  const buildPath = `/builds/${buildId}`, build = await get(buildPath);
+  if (['FAILED', 'INVALID'].includes(build.data?.attributes?.processingState)) handoff.fail('processing_failed');
+  if (build.data?.attributes?.processingState === 'PROCESSING') return null;
+  const files = await get(`/buildUploads/${receipt.upload_id}/buildUploadFiles`);
+  const assets = files.data?.filter(row => row.attributes?.assetType === 'ASSET');
+  if (!Array.isArray(assets) || files.links?.next || assets.length !== 1 || assets[0].id !== receipt.file_id) {
+    handoff.fail('file_membership');
+  }
+  // Preserve the existing independent complete-file, VALID/eligible build and actual app readbacks.
+  return apple.verifyApple(receipt, requested => requested === path ? response :
+    requested === buildPath ? build : get(requested));
+}
+
+async function verify(value, artifactId, timeout, dependencies = {}) {
+  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 3600) handoff.fail('timeout_invalid');
+  const api = dependencies.api || github, now = dependencies.now || Date.now;
+  const sleep = dependencies.sleep || delay, started = now(), deadline = started + timeout * 1000;
+  const key = dependencies.get ? null : credential();
+  const get = dependencies.get || (path => apple.appleGet(path, key, Math.max(1, Math.min(30000, deadline - now()))));
+  await handoff.verifyProducer(value, artifactId, api);
+  await handoff.phase(value, api);
+  let proof;
+  do {
+    proof = await observe(value.receipt, get);
+    if (proof) break;
+    if (now() >= deadline) handoff.fail('processing_pending');
+    await sleep(Math.min(10000, deadline - now()));
+  } while (now() < deadline);
+  if (!proof) handoff.fail('processing_pending');
+  const prior = await handoff.phase(value, api);
+  if (prior === 'uploading') await api.status(value.owner.deployment_id, 'uploaded', 'success');
+  if (await handoff.phase(value, api) !== 'uploaded') handoff.fail('write_unconfirmed');
+  return {schema: 'gowalk-cicd/apple-upload-verified.v1', state: prior === 'uploaded' ? 'reused' : 'landed',
+    deployment_id: value.owner.deployment_id, producer_attempt: value.owner.run_attempt,
+    processing_seconds: (now() - started) / 1000, ...proof};
+}
+
+async function main() {
+  const {values, positionals} = parseArgs({allowPositionals: true, options: {
+    sha256: {type: 'string'}, 'producer-attempt': {type: 'string'}, timeout: {type: 'string', default: '900'}}});
+  if (positionals.length !== 1) handoff.fail('arguments');
+  const value = handoff.read(positionals[0], values.sha256, Number(values['producer-attempt']));
+  const proof = await verify(value, Number(process.env.APPLE_UPLOAD_HANDOFF_ARTIFACT_ID), Number(values.timeout));
+  handoff.metadata(value);
+  const receiptPath = `${positionals[0]}.upload-receipt.json`;
+  fs.writeFileSync(receiptPath, JSON.stringify({...value.receipt, stage: 'complete', state: 'COMPLETE',
+    build_id: proof.build_id, processing_seconds: proof.processing_seconds}, null, 2) + '\n');
+  if (/[\r\n]/.test(receiptPath)) handoff.fail('receipt_path');
+  if (process.env.GITHUB_OUTPUT) fs.appendFileSync(process.env.GITHUB_OUTPUT,
+    `verified=true\nbuild-id=${proof.build_id}\nproducer-attempt=${proof.producer_attempt}\n` +
+    `receipt-path=${receiptPath}\n`);
+  fs.writeFileSync(`${positionals[0]}.verified.json`, JSON.stringify(proof, null, 2) + '\n');
+  console.log(JSON.stringify(proof));
+}
+
+if (require.main === module) main().catch(error => {
+  const code = /^(apple_upload_verify|apple_upload_reconcile|mobile_release)_[a-z0-9_]+$/.test(error?.message || '') ?
+    error.message : 'apple_upload_verify_unavailable';
+  console.error('::error title=apple_upload_verification_failed::' + JSON.stringify({code}));
+  process.exitCode = 1;
+});
+module.exports = {credential, observe, verify, main};

package/action/scripts/mobile_artifact_inventory.cjs

@@ -39,7 +39,7 @@ async function candidate(artifact) {
       producers[0].head_sha !== run.head_sha || !producers[0].steps?.some(step =>
         step.name === 'Retain candidate shipping binary' && step.conclusion === 'success')) return null;
   // Re-running only a failed sibling retains a successful platform's artifact from its earlier attempt.
-  return {...run, artifact_attempt: attempt};
+  return {...run, artifact_attempt: attempt, cache_runner_labels: producers[0].labels};
 }
 
 // The newest reusable candidate for this platform's current inputs, or null; reads only.
@@ -190,6 +190,7 @@ function pack(platform) {
   mkdirSync(directory, {recursive: true});
   execFileSync('python3', [join(__dirname, 'mobile_artifact_files.py'), 'pack', platform, directory],
     {stdio: ['ignore', 'inherit', 'pipe'], env: {...process.env, MOBILE_ARTIFACT_FINGERPRINT: fingerprint}});
+  require('./mobile_dependency_cache.cjs').record(directory, platform);
   output('directory', directory);
   const attempt = `${process.env.GITHUB_RUN_ID}-${process.env.GITHUB_RUN_ATTEMPT}`;
   output('name', `mobile-binary-${platform}-${fingerprint}-${attempt}`);

package/action/scripts/mobile_cache_version.cjs

@@ -0,0 +1,29 @@
+/* actions/cache@caa2961 bundles @actions/cache 5.1.0: raw paths, compression, salt 1.0. */
+'use strict';
+const {createHash} = require('node:crypto');
+const {spawnSync} = require('node:child_process');
+const {homedir} = require('node:os');
+
+function compression(run = spawnSync) {
+  const result = run('zstd', ['--quiet', '--version'], {encoding: 'utf8', timeout: 3000, maxBuffer: 4096});
+  if (result.error?.code === 'ENOENT') return 'gzip';
+  if (result.error || result.status !== 0) throw Error('dependency_cache_compression_unknown');
+  return `${result.stdout || ''}${result.stderr || ''}`.trim() ? 'zstd-without-long' : 'gzip';
+}
+
+function version(paths, method) {
+  if (!Array.isArray(paths) || !paths.length || paths.some(path => typeof path !== 'string' ||
+      !path || /[\r\n|]/.test(path)) || !['gzip', 'zstd-without-long'].includes(method)) {
+    throw Error('dependency_cache_paths_invalid');
+  }
+  return createHash('sha256').update([...paths, method, '1.0'].join('|')).digest('hex');
+}
+
+function versions(keys, flutter, method = compression()) {
+  const paths = {sdk: [flutter.sdk_path], pub: [flutter.pub_path],
+    pods: ['ios/Pods', '~/Library/Caches/CocoaPods'],
+    gradle: [`${homedir()}/.gradle/caches`, `${homedir()}/.gradle/wrapper`]};
+  return Object.fromEntries(Object.keys(keys).map(name => [name, version(paths[name], method)]));
+}
+
+module.exports = {compression, version, versions};

package/action/scripts/mobile_dependency_cache.cjs

@@ -0,0 +1,123 @@
+/* Prime missing default-branch dependencies using keys, never bytes, from a verified candidate. */
+'use strict';
+const {appendFileSync, readFileSync, writeFileSync, existsSync} = require('node:fs');
+const {join, relative, resolve, isAbsolute} = require('node:path');
+const {execFileSync} = require('node:child_process');
+const inventory = require('./mobile_artifact_inventory.cjs');
+const api = require('./mobile_release_api.cjs');
+const cache = require('./mobile_cache_version.cjs');
+const PREFIX = {sdk: 'flutter-', pub: 'flutter-pub-', pods: 'pods-macOS-',
+  gradle: 'setup-java-Linux-'};
+
+function valid(value, platform) {
+  if (value?.schema !== 1 || value.os !== (platform === 'ios' ? 'macOS' : 'Linux') ||
+      !['ARM64', 'X64'].includes(value.arch) || !value.keys || typeof value.keys !== 'object') return false;
+  const entries = Object.entries(value.keys);
+  if (!entries.length || entries.length > 4 || entries.some(([name, key]) => !PREFIX[name] ||
+      typeof key !== 'string' || !key.startsWith(PREFIX[name]) || !/^[\w.-]{1,500}$/.test(key))) return false;
+  if (!value.versions || entries.some(([name]) => !/^[a-f0-9]{64}$/.test(value.versions[name] || ''))) return false;
+  if (Boolean(value.keys.sdk) !== Boolean(value.keys.pub)) return false;
+  if (value.keys.sdk && !/^\d+\.\d+\.\d+$/.test(value.flutter_version || '')) return false;
+  if (platform === 'ios' && value.keys.gradle || platform === 'android' && value.keys.pods) {
+    return false;
+  }
+  return typeof value.container === 'string' && !isAbsolute(value.container) &&
+    !value.container.split(/[\\/]/).includes('..') && !/[\r\n]/.test(value.container);
+}
+
+function record(directory, platform) {
+  const env = process.env, keys = {};
+  let flutter;
+  try { flutter = JSON.parse(env.MOBILE_CACHE_FLUTTER_IDENTITY || '{}'); } catch { return; }
+  for (const name of Object.keys(PREFIX)) {
+    const key = env[`MOBILE_CACHE_${name.toUpperCase()}_KEY`];
+    if (key) keys[name] = key;
+  }
+  if (flutter.sdk && flutter.pub) Object.assign(keys, {sdk: flutter.sdk, pub: flutter.pub});
+  if (keys.pub && !keys.sdk) delete keys.pub;
+  if (keys.pods && !existsSync(join(env.GITHUB_WORKSPACE, 'ios/Podfile.lock'))) delete keys.pods;
+  if (!Object.keys(keys).length) return;
+  const container = env.CFG_WORKSPACE || env.CFG_PROJECT || '';
+  let versions;
+  try { versions = cache.versions(keys, flutter); } catch { return; }
+  const value = {schema: 1, keys, versions, os: env.RUNNER_OS, arch: env.RUNNER_ARCH,
+    flutter_version: flutter.version || '',
+    container: container ? relative(env.GITHUB_WORKSPACE, resolve(env.GITHUB_WORKSPACE, container)) : ''};
+  if (!valid(value, platform)) return;
+  const path = join(directory, 'mobile-binary.json');
+  const receipt = JSON.parse(readFileSync(path, 'utf8'));
+  receipt.dependency_caches = value;
+  writeFileSync(path, JSON.stringify(receipt, null, 2) + '\n');
+}
+
+async function missing(value, branch, read = api.request) {
+  const absent = await Promise.all(Object.entries(value.keys).map(async ([name, key]) => {
+    const query = new URLSearchParams({ref: `refs/heads/${branch}`, key, per_page: '100'});
+    const response = await read('GET', `/actions/caches?${query}`, undefined, 5000);
+    if (!Array.isArray(response.actions_caches)) throw Error('dependency_cache_inventory_unknown');
+    // A partial Gradle download is useful, but cannot certify completed dependency priming.
+    const found = response.actions_caches.some(row => row.ref === `refs/heads/${branch}` &&
+      row.size_in_bytes > 0 && row.version === value.versions[name] &&
+      (row.key === key || name === 'gradle' && row.key.startsWith(`${key}-warm-`)));
+    return found ? null : name;
+  }));
+  return absent.filter(Boolean);
+}
+
+async function plan(platform, branch, dependencies = {inventory, missing}) {
+  const deadline = Date.now() + 30000;
+  const found = await dependencies.inventory.find(platform, deadline);
+  if (!found) return null;
+  const receipt = await dependencies.inventory.remoteReceipt(found.artifact, deadline);
+  if (receipt.run_id !== found.run.id || receipt.run_attempt !== found.run.artifact_attempt ||
+      receipt.head_sha !== found.run.head_sha || receipt.repository !== process.env.GITHUB_REPOSITORY ||
+      receipt.platform !== platform || receipt.fingerprint !== found.fingerprint ||
+      !valid(receipt.dependency_caches, platform)) return null;
+  const labels = found.run.cache_runner_labels || [];
+  const runner = platform === 'ios' ? labels.find(label => /^macos-(15|26)(-intel)?$/.test(label)) : '';
+  if (platform === 'ios' && (!runner || labels.includes('self-hosted'))) return null;
+  const absent = await dependencies.missing(receipt.dependency_caches, branch);
+  return absent.length ? {...receipt.dependency_caches, runner, missing: absent} : null;
+}
+
+async function main() {
+  const event = JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8'));
+  const run = event.workflow_run, branch = event.repository?.default_branch;
+  if (run?.conclusion !== 'success' || run.event !== 'push' || run.head_branch !== branch ||
+      run.head_repository?.full_name !== process.env.GITHUB_REPOSITORY) return;
+  if (execFileSync('git', ['rev-parse', 'HEAD'], {encoding: 'utf8'}).trim() !== run.head_sha) return;
+  const intent = JSON.parse(readFileSync('.factory/releases/mobile.json', 'utf8'));
+  for (const platform of ['ios', 'android']) {
+    if (!intent.platforms?.[platform]) continue;
+    try {
+      const value = await plan(platform, branch);
+      if (value) appendFileSync(process.env.GITHUB_OUTPUT, `${platform}=${JSON.stringify(value)}\n`);
+      console.log(`Dependency cache ${platform}: ${value ? value.missing.join(',') : 'no missing verified keys'}`);
+    } catch { console.log(`::notice::Dependency cache ${platform}: inventory unavailable; skipping optional priming`); }
+  }
+}
+
+function verify(hostOnly = false) {
+  const value = JSON.parse(process.env.MOBILE_CACHE_PLAN || '{}');
+  const platform = process.env.RUNNER_OS === 'macOS' ? 'ios' : 'android';
+  if (!valid(value, platform) || value.os !== process.env.RUNNER_OS || value.arch !== process.env.RUNNER_ARCH) {
+    throw Error('dependency_cache_host_changed');
+  }
+  if (hostOnly) return;
+  for (const [name, key] of Object.entries(value.keys)) {
+    let actual = process.env[`MOBILE_CACHE_${name.toUpperCase()}_KEY`];
+    if (name === 'pub') actual += `-${process.env.MOBILE_CACHE_PUB_LOCK || ''}`;
+    if (actual !== key) throw Error('dependency_cache_key_changed');
+  }
+  const versions = cache.versions(value.keys, {sdk_path: process.env.MOBILE_CACHE_SDK_PATH,
+    pub_path: process.env.MOBILE_CACHE_PUB_PATH});
+  if (Object.keys(value.keys).some(name => versions[name] !== value.versions[name])) {
+    throw Error('dependency_cache_version_changed');
+  }
+}
+
+module.exports = {valid, record, missing, plan, verify, main};
+if (require.main === module && process.argv[2] === 'verify') verify(process.argv[3] === '--host-only');
+else if (require.main === module) main().catch(() => {
+  console.log('::notice::Dependency cache plan unavailable; required builds retain dependency resolution');
+});

package/action/scripts/prime_native_dependencies.py

@@ -0,0 +1,47 @@
+"""Resolve committed CocoaPods/pub inputs on a trusted CI cache miss; never build or sign."""
+import json
+import os
+from pathlib import Path
+import signal
+import subprocess
+
+import native_pods
+
+
+def flutter(*arguments):
+    child = subprocess.Popen(["flutter", *arguments], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                             start_new_session=True)
+    try:
+        if child.wait(timeout=120):
+            raise RuntimeError("dependency_priming_failed")
+    finally:
+        if child.poll() is None:
+            os.killpg(child.pid, signal.SIGTERM)
+            try:
+                child.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                os.killpg(child.pid, signal.SIGKILL)
+                child.wait(timeout=5)
+
+
+def prime(value, root):
+    if os.environ.get("GITHUB_ACTIONS") != "true":
+        raise RuntimeError("dependency_priming_requires_ci")
+    if value.get("keys", {}).get("sdk") and set(value["missing"]) & {"pub", "pods"}:
+        flutter("pub", "get")
+        if "pods" in value["missing"]:
+            flutter("precache", "--ios")
+    if "pods" in value["missing"]:
+        native_pods.prepare(root, value["container"])
+
+
+def interrupted(*_args):
+    raise KeyboardInterrupt
+
+
+if __name__ == "__main__":
+    signal.signal(signal.SIGTERM, interrupted)
+    try:
+        prime(json.loads(os.environ["MOBILE_CACHE_PLAN"]), Path(os.environ["GITHUB_WORKSPACE"]))
+    except (OSError, ValueError, RuntimeError, native_pods.guard.Refused, subprocess.SubprocessError):
+        raise SystemExit("Dependency priming unavailable; no completed Pods cache was saved") from None

package/action/scripts/upload_build.py

@@ -17,6 +17,7 @@ import asc_common
 import requests
 import upload_checksums
 import upload_receipt
+import apple_upload_handoff
 from upload_receipt import Receipt, UploadError
 
 # Provider refusals the uploader classifies itself instead of letting the shared
@@ -149,7 +150,11 @@ def transfer_all(ipa: Path, file: dict, info: dict) -> None:
     }})
 
 
-def deliver(ipa: Path, report: Path, timeout: int) -> dict:
+def deliver(ipa: Path, report: Path, timeout: int, handoff: Path | None = None) -> dict:
+    if handoff and (any(char in str(handoff) for char in "\r\n")
+                    or not handoff.parent.is_dir() or handoff.is_dir()):
+        raise ValueError("apple_handoff_path_invalid")
+    deferred = apple_upload_handoff.prepare() if handoff else None
     receipt = Receipt(report)
     receipt.update("identity", **identity(ipa))
     app_id = os.environ.get("APP_STORE_APPLE_ID") or ""
@@ -165,6 +170,9 @@ def deliver(ipa: Path, report: Path, timeout: int) -> dict:
     receipt.update("file_reserved", file_id=file["id"])
     transfer_all(ipa, file, info)
     receipt.update("transferred")
+    if handoff:
+        apple_upload_handoff.write(handoff, deferred, receipt.data)
+        return dict(receipt.data)
     processing_started = time.monotonic()
     deadline = processing_started + timeout
     while True:
@@ -190,9 +198,13 @@ def main() -> None:
     parser.add_argument("ipa", type=Path)
     parser.add_argument("--report", required=True, type=Path)
     parser.add_argument("--timeout", type=int, default=900)
+    parser.add_argument("--transfer-only", action="store_true")
+    parser.add_argument("--handoff", type=Path)
     args = parser.parse_args()
+    if args.transfer_only != bool(args.handoff):
+        parser.error("--transfer-only and --handoff must be supplied together")
     try:
-        receipt = deliver(args.ipa, args.report, args.timeout)
+        receipt = deliver(args.ipa, args.report, args.timeout, args.handoff)
     except (OSError, ValueError, KeyError, RuntimeError, SystemExit) as exc:
         # The receipt and annotation carry the classified category and identifiers only;
         # exception text can quote provider bodies or transport details and stays out.

package/android-action/flutter-setup/action.yml

@@ -280,3 +280,20 @@ runs:
     with:
       path: ${{ steps.flutter-action.outputs.CACHE-PATH }}
       key: ${{ steps.flutter-action.outputs.CACHE-KEY }}
+  - name: Retain the resolved dependency cache identities
+    if: ${{ inputs.cache == 'true' && inputs.dry-run != 'true' && steps.install.outcome == 'success' }}
+    continue-on-error: true
+    shell: python3 {0}
+    env:
+      CACHE_SDK: ${{ steps.flutter-action.outputs.CACHE-KEY }}
+      CACHE_PUB: ${{ steps.flutter-action.outputs.PUB-CACHE-KEY }}-${{ hashFiles('**/pubspec.lock') }}
+      CACHE_SDK_PATH: ${{ steps.flutter-action.outputs.CACHE-PATH }}
+      CACHE_PUB_PATH: ${{ steps.flutter-action.outputs.PUB-CACHE-PATH }}
+      CACHE_VERSION: ${{ steps.flutter-action.outputs.VERSION }}
+    run: |
+      import json, os
+      value = {key: os.environ['CACHE_' + key.upper()] for key in ('sdk', 'pub', 'version', 'sdk_path', 'pub_path')}
+      if any(not text or len(text) > 500 or '\n' in text or '\r' in text for text in value.values()):
+          raise SystemExit('Dependency cache identity unavailable')
+      with open(os.environ['GITHUB_ENV'], 'a') as output:
+          output.write('MOBILE_CACHE_FLUTTER_IDENTITY=' + json.dumps(value, separators=(',', ':')) + '\n')