release(1.5.3): reconcile master into develop

.github/actions/checkout-release-source/action.yml

@@ -0,0 +1,26 @@
+name: Checkout complete release source
+description: Avoid unshallowing a reused CI checkout before fetching release history.
+inputs:
+  ref:
+    description: Exact source ref or commit accepted by the calling release job.
+    default: ''
+  fetch-depth:
+    description: History depth; release jobs require complete history.
+    default: '0'
+  persist-credentials:
+    description: Preserve the calling job's existing checkout credential policy.
+    default: 'true'
+runs:
+  using: composite
+  steps:
+    - name: Retire only the inherited shallow CI Git metadata
+      uses: actions/github-script@v9
+      env:
+        ZSTANDARD_CHECKOUT_BOOTSTRAP: ${{ github.action_path }}/retire-shallow-cache.cjs
+      with:
+        script: return require(process.env.ZSTANDARD_CHECKOUT_BOOTSTRAP)({core});
+    - uses: actions/checkout@v6
+      with:
+        ref: ${{ inputs.ref }}
+        fetch-depth: ${{ inputs.fetch-depth }}
+        persist-credentials: ${{ inputs.persist-credentials }}

.github/actions/checkout-release-source/retire-shallow-cache.cjs

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {execFileSync} = require('node:child_process');
+
+module.exports = function retireShallowCache({core, env = process.env}) {
+  const repository = env.GITHUB_REPOSITORY || '';
+  if (env.GITHUB_ACTIONS !== 'true' || !/^[\w.-]+\/[\w.-]+$/.test(repository)) {
+    throw new Error('Release checkout requires a GitHub Actions repository workspace.');
+  }
+  const workspace = fs.realpathSync.native(env.GITHUB_WORKSPACE);
+  const temporary = fs.realpathSync.native(env.RUNNER_TEMP);
+  const name = repository.split('/')[1];
+  const expected = path.join(path.dirname(temporary), name, name);
+  const equal = (a, b) => process.platform === 'win32'
+    ? a.toLowerCase() === b.toLowerCase() : a === b;
+  if (!equal(workspace, expected) || fs.lstatSync(env.GITHUB_WORKSPACE).isSymbolicLink()) {
+    throw new Error('Refusing to alter Git metadata outside the runner-owned repository workspace.');
+  }
+  const metadata = path.join(workspace, '.git');
+  let information;
+  try { information = fs.lstatSync(metadata); }
+  catch (error) { if (error.code === 'ENOENT') return {retired: false}; throw error; }
+  if (!information.isDirectory() || information.isSymbolicLink()) {
+    throw new Error('Refusing a linked Git directory or worktree.');
+  }
+  const git = (...args) => execFileSync('git', ['-C', workspace, ...args], {
+    env: {...env, GIT_OPTIONAL_LOCKS: '0'}, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+  if (git('rev-parse', '--is-shallow-repository') !== 'true') return {retired: false};
+  const origin = new URL(git('config', '--get', 'remote.origin.url'));
+  if (origin.protocol !== 'https:' || origin.hostname !== 'github.com'
+      || origin.username || origin.password
+      || origin.pathname.replace(/\.git$/, '').replace(/^\//, '').toLowerCase() !== repository.toLowerCase()) {
+    throw new Error('The shallow cache does not belong to the calling GitHub repository.');
+  }
+  for (const name of ['worktrees', 'modules']) {
+    const directory = path.join(metadata, name);
+    if (fs.existsSync(directory) && fs.readdirSync(directory).length) {
+      throw new Error('Retaining Git metadata with registered worktrees or submodules.');
+    }
+  }
+  for (const name of ['index.lock', 'shallow.lock', 'HEAD.lock']) {
+    if (fs.existsSync(path.join(metadata, name))) throw new Error('Retaining locked Git metadata.');
+  }
+  try { git('diff', '--quiet'); git('diff', '--cached', '--quiet'); }
+  catch { throw new Error('Could not verify clean tracked source; retaining the CI Git metadata.'); }
+  if (git('ls-files', '--others', '--exclude-standard') || git('for-each-ref', '--format=%(objectname)', 'refs/stash')) {
+    throw new Error('Retaining unexpected untracked files or stashed work in the CI workspace.');
+  }
+  const publicRefs = new Set(git('for-each-ref', '--format=%(objectname)', 'refs/remotes', 'refs/tags').split('\n'));
+  const branches = git('for-each-ref', '--format=%(objectname)', 'refs/heads').split('\n').filter(Boolean);
+  if (branches.some(oid => !publicRefs.has(oid))) {
+    throw new Error('Retaining a local branch that is not represented by the cached remote refs.');
+  }
+  const backup = fs.mkdtempSync(path.join(temporary, 'zstandard-shallow-git-'));
+  fs.chmodSync(backup, 0o700);
+  fs.writeFileSync(path.join(backup, '.owner'), JSON.stringify({repository, run: env.GITHUB_RUN_ID,
+    attempt: env.GITHUB_RUN_ATTEMPT, head: git('rev-parse', 'HEAD')}), {mode: 0o600});
+  fs.renameSync(metadata, path.join(backup, 'git'));
+  core.notice('Retired shallow CI Git metadata to private job temporary storage; checkout will fetch complete history.');
+  return {retired: true};
+};

.github/actions/copilot-verification-setup/action.yml

@@ -1,13 +1,40 @@
-# Created once by Copilot setup. This action and its assets belong to your project.
-# Replace the placeholder with reviewed runtime/dependency setup, then merge onto MAIN_BRANCH.
+# Project-owned dependency setup, executed by Copilot's existing coordinator.
 name: Prepare project verification
-description: Configure project dependencies before enabling VERIFICATION_SETUP.
+description: Provision the tested Flutter/Dart SDK before project verification.
 runs:
   using: composite
   steps:
-    - name: Configure project verification dependencies
+    - name: Select private package and configuration paths
       shell: bash
       run: |
-        printf '%s\n' 'Configure .github/actions/copilot-verification-setup/action.yml with your project dependencies before enabling VERIFICATION_SETUP.'
-        printf '%s\n' 'Replace this failing placeholder, review and merge it onto the configured MAIN_BRANCH, then run a real verification.'
-        exit 1
+        set -euo pipefail
+        mkdir -p "$HOME/.pub-cache/bin" "$HOME/.config"
+        printf 'PUB_CACHE=%s\nXDG_CONFIG_HOME=%s\n' "$HOME/.pub-cache" "$HOME/.config" >> "$GITHUB_ENV"
+    - name: Install the tested Flutter SDK
+      uses: subosito/flutter-action@v2
+      with:
+        channel: stable
+        flutter-version: '3.47.2'
+        architecture: ${{ runner.arch == 'ARM64' && 'arm64' || 'x64' }}
+        cache-path: '${{ runner.tool_cache }}/zstandard-flutter-v2/:channel:-:version:-:arch:'
+        cache: false
+        pub-cache: false
+    - name: Prepare private Linux test dependencies
+      if: runner.os == 'Linux'
+      shell: bash
+      env:
+        DESKTOP: 'true'
+        COVERAGE: 'false'
+        ANDROID: 'false'
+        ARM64: 'false'
+        BROWSER: 'false'
+      run: ZSTANDARD_LINUX_STATE_ROOT="$HOME" bash "$GITHUB_ACTION_PATH/linux-dependencies.sh"
+    - name: Preserve native tool settings through the supported PATH handoff
+      shell: bash
+      run: bash "$GITHUB_ACTION_PATH/runtime-launchers.sh"
+    - name: Verify the provisioned SDK
+      shell: bash
+      run: |
+        set -euo pipefail
+        flutter --version
+        dart --version

.github/actions/copilot-verification-setup/linux-dependencies.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# Shared private Linux dependencies for platform CI and project verification.
+set -euo pipefail
+command -v apt-get >/dev/null
+command -v apt-cache >/dev/null
+command -v dpkg-query >/dev/null
+packages=(build-essential clang cmake coreutils ninja-build pkg-config curl unzip)
+browser_missing=()
+if [[ "$ANDROID" == 'true' ]]; then
+  packages+=(libdbus-1-3 libfontconfig1 libgl1 libnss3 libpulse0 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxi6 libxrandr2 libxrender1 libxtst6)
+fi
+if [[ "$BROWSER" == 'true' ]]; then
+  packages+=(ca-certificates libdbus-1-3 libdrm2 libgbm1 libnspr4 libnss3 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxdamage1 libxext6 libxfixes3 libxkbcommon0 libxrandr2)
+  # Ubuntu/Debian releases before the time64 transition use the base
+  # names. Reuse installed variants or resolve against private indexes.
+  for legacy in libasound2 libatk-bridge2.0-0 libatk1.0-0 libatspi2.0-0 libcups2; do
+    selected=''
+    for candidate in "${legacy}t64" "$legacy"; do
+      if [[ "$(dpkg-query -W -f='${Status}' "$candidate" 2>/dev/null || true)" == 'install ok installed' ]]; then
+        selected="$candidate"
+        break
+      fi
+    done
+    if [[ -n "$selected" ]]; then packages+=("$selected"); else browser_missing+=("$legacy"); fi
+  done
+fi
+if [[ "$DESKTOP" == 'true' ]]; then packages+=(libgtk-3-dev xvfb); fi
+if [[ "$COVERAGE" == 'true' ]]; then packages+=(bc lcov); fi
+if [[ "$ARM64" == 'true' ]]; then packages+=(gcc-aarch64-linux-gnu g++-aarch64-linux-gnu); fi
+missing=()
+for package in "${packages[@]}"; do
+  if [[ "$(dpkg-query -W -f='${Status}' "$package" 2>/dev/null || true)" != 'install ok installed' ]]; then
+    missing+=("$package")
+  fi
+done
+if [[ "${#missing[@]}" -eq 0 && "${#browser_missing[@]}" -eq 0 ]]; then
+  echo 'All selected Linux prerequisites are already installed.'
+  exit 0
+fi
+state_root="${ZSTANDARD_LINUX_STATE_ROOT:-$RUNNER_TEMP}"
+state="$(mktemp -d "$state_root/zstandard-linux-tools.XXXXXX")"
+mkdir -p "$state/apt/lists/partial" "$state/packages/partial" "$state/prefix"
+cp /var/lib/dpkg/status "$state/apt/status"
+apt_options=(-o "Dir::State::status=$state/apt/status" -o "Dir::State::Lists=$state/apt/lists" -o "Dir::Cache::archives=$state/packages" -o "Dir::Cache::pkgcache=$state/apt/pkgcache.bin" -o "Dir::Cache::srcpkgcache=$state/apt/srcpkgcache.bin" -o Acquire::Retries=0 -o Acquire::http::Timeout=30 -o Acquire::https::Timeout=30)
+apt-get "${apt_options[@]}" update
+for legacy in "${browser_missing[@]}"; do
+  apt_candidate="$(LC_ALL=C apt-cache "${apt_options[@]}" policy "${legacy}t64" | sed -n 's/^  Candidate: //p')"
+  if [[ -n "$apt_candidate" && "$apt_candidate" != '(none)' ]]; then
+    missing+=("${legacy}t64")
+  else
+    missing+=("$legacy")
+  fi
+done
+apt-get "${apt_options[@]}" --download-only --assume-yes --no-install-recommends install "${missing[@]}"
+for package in "$state/packages/"*.deb; do
+  [[ -f "$package" ]] || continue
+  dpkg-deb --extract "$package" "$state/prefix"
+done
+prefix="$state/prefix"
+# pkg-config needs both extracted and preinstalled headers/libraries.
+# Fill only missing private paths with links; never traverse a target link.
+overlay_system() {
+  local source="$1" target="$2" child destination
+  [[ -d "$source" && ! -L "$source" && ! -L "$target" ]] || return 0
+  mkdir -p "$target"
+  for child in "$source/"*; do
+    [[ -e "$child" || -L "$child" ]] || continue
+    destination="$target/${child##*/}"
+    if [[ -L "$destination" ]]; then
+      continue
+    elif [[ -d "$destination" && -d "$child" && ! -L "$child" ]]; then
+      overlay_system "$child" "$destination"
+    elif [[ ! -e "$destination" ]]; then
+      ln -s "$child" "$destination"
+    fi
+  done
+}
+case "$(dpkg --print-architecture)" in
+  amd64) multiarch=x86_64-linux-gnu ;;
+  arm64) multiarch=aarch64-linux-gnu ;;
+  *) echo 'Unsupported Linux runner architecture.' >&2; exit 1 ;;
+esac
+overlay_system /usr/include "$prefix/usr/include"
+overlay_system "/usr/lib/$multiarch" "$prefix/usr/lib/$multiarch"
+overlay_system /usr/share/pkgconfig "$prefix/usr/share/pkgconfig"
+for directory in lib lib64 bin sbin; do
+  if [[ ! -e "$prefix/$directory" && ! -L "$prefix/$directory" ]]; then
+    ln -s "usr/$directory" "$prefix/$directory"
+  fi
+done
+overlay_system "/lib/$multiarch" "$prefix/lib/$multiarch"
+# GNU linker scripts carry absolute development-library paths. Relocate
+# only regular private scripts; shared host libraries remain read-only.
+while IFS= read -r -d '' linker_script; do
+  if grep -Iq '^/\* GNU ld script' "$linker_script"; then
+    ZSTANDARD_LINUX_PREFIX="$prefix" /usr/bin/perl -0pi -e '
+      s{(?<![\w"])(/[A-Za-z0-9_./+-]+)}{
+        my $path = $ENV{"ZSTANDARD_LINUX_PREFIX"} . $1;
+        if (-e $path) {
+          $path =~ s/([\\"])/\\$1/g;
+          qq("$path")
+        } else { $1 }
+      }ge
+    ' "$linker_script"
+  fi
+done < <(find "$prefix" -type f -name '*.so' -print0)
+lcov_module="$prefix/usr/lib/lcov/lcovutil.pm"
+if [[ -f "$lcov_module" && ! -L "$lcov_module" ]]; then
+  sed -i 's|^our \$tool_dir.*;|our $tool_dir = $ENV{"ZSTANDARD_LCOV_BIN"} // "/usr/bin";|' "$lcov_module"
+fi
+libraries="$prefix/usr/lib/$multiarch:$prefix/usr/lib:$prefix/lib/$multiarch:$prefix/lib"
+for directory in "$prefix/usr/lib/"llvm*/lib; do
+  if [[ -d "$directory" ]]; then libraries="$libraries:$directory"; fi
+done
+perl_libraries="$prefix/usr/lib/lcov:$prefix/usr/share/perl5"
+for directory in "$prefix/usr/share/perl/"* "$prefix/usr/lib/$multiarch/perl5/"* "$prefix/usr/lib/$multiarch/perl/"*; do
+  if [[ -d "$directory" ]]; then perl_libraries="$perl_libraries:$directory"; fi
+done
+{
+  printf 'ZSTANDARD_LCOV_BIN=%s/usr/bin\n' "$prefix"
+  printf 'PERL5LIB=%s%s\n' "$perl_libraries" "${PERL5LIB:+:$PERL5LIB}"
+  printf 'LD_LIBRARY_PATH=%s%s\n' "$libraries" "${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+  if [[ "$ANDROID" != 'true' ]]; then
+    printf 'LIBRARY_PATH=%s%s\n' "$libraries" "${LIBRARY_PATH:+:$LIBRARY_PATH}"
+    printf 'CPATH=%s/usr/include:%s/usr/include/%s%s\n' "$prefix" "$prefix" "$multiarch" "${CPATH:+:$CPATH}"
+    printf 'PKG_CONFIG_PATH=%s/usr/lib/%s/pkgconfig:%s/usr/share/pkgconfig%s\n' "$prefix" "$multiarch" "$prefix" "${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
+    printf 'PKG_CONFIG_SYSROOT_DIR=%s\n' "$prefix"
+    printf 'CMAKE_PREFIX_PATH=%s/usr%s\n' "$prefix" "${CMAKE_PREFIX_PATH:+:$CMAKE_PREFIX_PATH}"
+  fi
+} >> "$GITHUB_ENV"
+printf '%s/usr/bin\n' "$prefix" >> "$GITHUB_PATH"

.github/actions/copilot-verification-setup/runtime-launchers.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Copilot forwards validated PATH entries; keep native tool configuration there.
+set -euo pipefail
+
+runtime_bin="$HOME/.zstandard-verification-runtime/bin"
+mkdir -p "$runtime_bin"
+for tool in flutter dart; do
+  executable="$(command -v "$tool")"
+  test -x "$executable"
+  {
+    printf '#!/usr/bin/env bash\nset -euo pipefail\n'
+    for setting in CPATH LIBRARY_PATH PKG_CONFIG_PATH PKG_CONFIG_SYSROOT_DIR CMAKE_PREFIX_PATH PUB_CACHE XDG_CONFIG_HOME; do
+      value="${!setting-}"
+      if [[ -n "$value" ]]; then
+        printf 'export %s=%q\n' "$setting" "$value"
+      fi
+    done
+    # The verifier may add the freshly built test plugin to its own search path.
+    if [[ -n "${LD_LIBRARY_PATH:-}" ]]; then
+      printf 'export LD_LIBRARY_PATH=%q"${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"\n' "$LD_LIBRARY_PATH"
+    fi
+    printf 'exec %q "$@"\n' "$executable"
+  } > "$runtime_bin/$tool"
+  chmod 700 "$runtime_bin/$tool"
+done
+printf '%s\n' "$runtime_bin" >> "$GITHUB_PATH"

.github/actions/preserve-flutter-project-files/action.yml

@@ -1,5 +1,5 @@
 name: Preserve Flutter project files
-description: Preserve files that Flutter may rewrite during dependency resolution.
+description: Preserve analysis options and tracked Apple host files that Flutter may rewrite.
 
 inputs:
   package:
@@ -12,7 +12,7 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Save or restore analysis options
+    - name: Save or restore Flutter project files
       shell: bash
       env:
         PACKAGE: ${{ inputs.package }}
@@ -21,6 +21,14 @@ runs:
         set -euo pipefail
         BACKUP_DIR="$RUNNER_TEMP/flutter-project-files/${PACKAGE//\//_}"
         files=("analysis_options.yaml" "example/analysis_options.yaml")
+        case "$PACKAGE" in
+          zstandard_ios|zstandard_macos)
+            platform="${PACKAGE#zstandard_}"
+            while IFS= read -r -d '' file; do
+              files+=("${file#"$PACKAGE/"}")
+            done < <(git ls-files -z -- "$PACKAGE/example/$platform/Runner.xcodeproj")
+            ;;
+        esac
 
         if [[ "$MODE" == 'save' ]]; then
           mkdir -p "$BACKUP_DIR"
@@ -33,6 +41,7 @@ runs:
         elif [[ "$MODE" == 'restore' ]]; then
           for file in "${files[@]}"; do
             if [[ -f "$BACKUP_DIR/$file" ]]; then
+              mkdir -p "$PACKAGE/$(dirname "$file")"
               cp "$BACKUP_DIR/$file" "$PACKAGE/$file"
             fi
           done

.github/actions/publish-package/action.yml

@@ -0,0 +1,41 @@
+name: Publish one immutable package
+description: Renew OIDC for each package and resolve only the distributable package.
+inputs:
+  package:
+    required: true
+    description: Name of the matched release package.
+  version:
+    required: true
+    description: Accepted stable release version.
+  dart-version:
+    required: true
+    description: Exact Dart SDK version bundled with the tested Flutter SDK.
+runs:
+  using: composite
+  steps:
+    # Each package gets a fresh credential after the previous indexing wait.
+    - uses: dart-lang/setup-dart@v1
+      with:
+        sdk: ${{ inputs.dart-version }}
+        # A nested SDK action inherits this composite's path, which has no
+        # analyzer matcher. Publication keeps its dry runs and CI gates.
+        problem-matcher: false
+    - name: Resolve, publish and wait for the exact version
+      shell: bash
+      env:
+        ZSTANDARD_PUBLISH_PACKAGE: ${{ inputs.package }}
+        ZSTANDARD_PUBLISH_VERSION: ${{ inputs.version }}
+      run: |
+        set -euo pipefail
+        case "$ZSTANDARD_PUBLISH_PACKAGE" in
+          zstandard|zstandard_platform_interface|zstandard_native|zstandard_android|zstandard_ios|zstandard_linux|zstandard_macos|zstandard_web|zstandard_windows|zstandard_cli) ;;
+          *) echo 'Unknown release package.' >&2; exit 2 ;;
+        esac
+        case "$ZSTANDARD_PUBLISH_PACKAGE" in
+          zstandard_native|zstandard_cli)
+            (cd "$ZSTANDARD_PUBLISH_PACKAGE" && dart pub get --no-example) ;;
+          *)
+            (cd "$ZSTANDARD_PUBLISH_PACKAGE" && flutter pub get --no-example) ;;
+        esac
+        dart run scripts/publish_if_missing.dart "$ZSTANDARD_PUBLISH_PACKAGE" "$ZSTANDARD_PUBLISH_VERSION"
+        dart run scripts/wait_for_pub_version.dart "$ZSTANDARD_PUBLISH_PACKAGE" "$ZSTANDARD_PUBLISH_VERSION" 1200