Native and Web Sync Flows

Native sync flow#

When native behavior or bindings need updates:

1. Make and release changes in llamadart-native or litert-lm-native first.
2. Sync native version and bindings in this repo.
3. Sync matching Apple SPM pins in the Flutter runtime companion packages under packages/ when Apple XCFramework releases changed.

The invariant is that core native-assets builds and Flutter Apple companion Swift Package Manager builds should resolve compatible bridge runtime releases. Do not point the core hook at leehack/*-native artifacts while companion Package.swift files point at unrelated Apple binaries; that creates different bridge behavior between pure Dart/macOS fallback and Flutter Apple builds.

Preferred in-repo workflow:

• .github/workflows/sync_native_bindings.yml

That workflow syncs llama.cpp headers, regenerates ffigen bindings, updates the native hook pins, updates companion package SPM pins, refreshes current README/website native pin docs, and opens a PR. It does not bump companion package versions by default. Use the sync script's explicit --bump-companion-versions option only when the same change intentionally prepares companion package releases. The native_tag input controls the llamadart-native release. The litert_lm_tag input defaults to keep; set it to a litert-lm-native tag or latest only when the LiteRT-LM native release should move in the same PR.

Local fallback:

tool/native/sync_native_headers_and_bindings.sh --tag latest
python3 tool/native/sync_native_release_pins.py \
  --llama-cpp-tag latest \
  --litert-lm-tag keep

After sync, run analyze/tests/docs checks before merge. For Apple SPM pin changes, verify the companion package changes under packages/, then run at least one Flutter iOS build and one macOS build with those packages enabled. Inspect the packaged frameworks to confirm the expected native release artifacts are present.

Native version update checklist#

Use this checklist in native sync PRs:

• Confirm llamadart-native or litert-lm-native has published the target release and the required per-platform native-assets archives.
• Confirm the same release provides Apple SPM-compatible XCFramework zip artifacts when companion package pins should move.
• Update hook/build.dart native pins with .github/workflows/sync_native_bindings.yml or tool/native/sync_native_release_pins.py.
• Update companion package Package.swift URL/checksum pins under packages/ when Apple XCFramework releases changed.
• Bump changed companion package versions only when that PR is intentionally preparing companion package releases; otherwise leave companion pub versions unchanged and let release prep own the version bump.
• Ensure each changed companion package README and CHANGELOG native-pin note names the new native repo tag when package contents change.
• Regenerate lib/src/backends/llama_cpp/bindings.dart whenever the llamadart-native header bundle changed.
• Update public docs that mention the pinned native versions or source table.

Companion package release handoff#

Native sync PRs can leave the repository in a state where the companion package source under packages/ is ready, but the corresponding pub.dev package version does not exist yet. That is expected before merge, but it must be resolved before tagging the next core llamadart release.

For every companion package whose pubspec.yaml version changed, or whose version is newly referenced by current install docs:

1. Confirm the Package.swift binary targets point at published native GitHub release assets and that the pinned checksums match those assets.
2. Merge the sync/release-prep PR first. The PR itself must not publish the companion or core package.
3. After merge, release_on_prep_merge.yml uses the release-prep PR merge as the publishing approval boundary and pushes each missing package-specific companion tag: llamadart_llama_cpp_flutter-v{{version}} or llamadart_litert_lm_flutter-v{{version}}.
4. Wait for publish_companion_pubdev.yml to pass.
5. Verify the version URL on pub.dev, for example https://pub.dev/api/packages/llamadart_llama_cpp_flutter/versions/{{version}}.
6. Only after the companion version is live, the automation pushes the core vX.Y.Z release tag that documents or depends on that companion version.

Web bridge asset sync flow#

When web bridge runtime behavior changes:

1. Update and release in llama-web-bridge.
2. Publish assets in llama-web-bridge-assets.
3. Update pinned assets in this repo.

Fetch pinned assets for local app web files:

WEBGPU_BRIDGE_ASSETS_TAG=<tag> ./scripts/fetch_webgpu_bridge_assets.sh

Validation after sync#

Use the contributor matrix to choose exact rows and record PR evidence:

dart run tool/testing/test_matrix.dart --list

• Native: model load/generation smoke checks on relevant platforms.
• Web: bridge load/fallback checks in example/chat_app.
• Docs: ensure version/platform notes match newly pinned runtime behavior.