fix: publish the b10545 Apple pin and drop the false Web parity claim - #447
fix: publish the b10545 Apple pin and drop the false Web parity claim#447leehack wants to merge 19 commits into
Conversation
Two things would have shipped wrong in 0.8.21. The Apple SwiftPM pin moved to b10545 after v0.8.20, but llamadart_llama_cpp_flutter stayed at 0.0.14, which is already on pub.dev. release_on_prep_merge.yml `continue`s past a companion whose version already exists, so the companion would have been skipped silently and Apple builds would have kept resolving the b10514 runtime. Bumping to 0.0.15 and moving the `## Unreleased` note into `## 0.0.15` makes the pin publishable. The WebGPU bridge docs claimed the pinned v0.1.37 assets embed llama.cpp b10514 "matching the default native runtime". The manifest does say b10514, but hook/build.dart moved to b10545, so the parity half became false a day after v0.8.20. docs_version_cut.yml snapshots website/docs on the release tag, which would have frozen the false sentence permanently. Both gates that should have caught these are extended rather than left as one-off fixes. verify_release_docs_versions.dart now checks each companion's Package.swift tag against the tag recorded in the CHANGELOG section its pubspec version will publish; it only compared hook/build.dart against Package.swift before, which is exactly why this passed. A pin still sitting in `## Unreleased` is the documented native-sync state, so it is reported as a pending bump by default and fails only under the new --release-prep flag, which release_on_prep_merge.yml now passes -- an unresolved bump aborts the release before any tag is pushed. check_webgpu_bridge_tag.dart now compares the bridge manifest's llama_cpp_tag against hook/build.dart's _llamaCppTag, with bridgeLlamaCppDivergence to record a deliberate divergence; a record left behind after the tags converge fails too, so the escape hatch cannot become permanent. --verify-manifest re-reads the published manifest so the recorded value stays honest, and the two doc sentences are registered pins so a reworded parity claim fails instead of outliving the pin it describes.
|
Chat app preview deployed for
|
There was a problem hiding this comment.
🟡 Changes recommended
The new gate code has a few confirmed failure-mode issues (uncaught JSON decode failures and uncaught file read exceptions) that can crash release tooling instead of reporting actionable errors.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR addresses two release blockers for the upcoming 0.8.21 prep by ensuring the llamadart_llama_cpp_flutter companion actually publishes the updated Apple SwiftPM pin, and by correcting (and enforcing via tooling) the WebGPU bridge docs’ Web/native llama.cpp parity statement.
Changes:
- Bump
llamadart_llama_cpp_flutterto0.0.15and update install snippets + lockfile so Apple builds no longer silently remain on the previously published pin. - Update WebGPU bridge documentation to state the pinned bridge assets embed a llama.cpp build that currently trails the native pin.
- Strengthen the release/documentation gates (
verify_release_docs_versions.dart,check_webgpu_bridge_tag.dart) and add unit tests + workflow wiring to prevent regressions.
File summaries
| File | Description |
|---|---|
| website/docs/platforms/webgpu-bridge.md | Updates docs to state bridge llama.cpp build trails native pin. |
| website/docs/maintainers/release-workflow.md | Updates release checklist to run strict --release-prep gate. |
| website/docs/getting-started/installation.md | Bumps companion dependency snippet to ^0.0.15. |
| website/docs/changelog/recent-releases.md | Notes the companion bump + corrected WebGPU parity docs. |
| tool/testing/verify_release_docs_versions.dart | Adds companion SwiftPM pin vs CHANGELOG verification + --release-prep. |
| tool/testing/test_matrix.dart | Updates matrix descriptions/commands to reflect new gate behavior. |
| tool/testing/check_webgpu_bridge_tag.dart | Adds Web/native llama.cpp drift checks + optional manifest verification. |
| test/unit/tooling/verify_release_docs_companion_pins_test.dart | New unit coverage for companion pin verification behavior. |
| test/unit/tooling/check_webgpu_bridge_tag_test.dart | Adds unit coverage for Web/native llama.cpp drift scenarios. |
| README.md | Updates install snippet to ^0.0.15. |
| packages/llamadart_llama_cpp_flutter/README.md | Updates companion install snippet to ^0.0.15. |
| packages/llamadart_llama_cpp_flutter/pubspec.yaml | Bumps package version to 0.0.15. |
| packages/llamadart_llama_cpp_flutter/CHANGELOG.md | Moves the documented pin into ## 0.0.15. |
| example/chat_app/pubspec.lock | Updates path dependency version to 0.0.15. |
| doc/webgpu_bridge.md | Updates docs to state bridge llama.cpp build trails native pin. |
| CHANGELOG.md | Notes companion bump + corrected WebGPU parity docs in core changelog. |
| AGENTS.md | Documents strict vs non-strict release docs verification behavior. |
| .github/workflows/release_on_prep_merge.yml | Runs verify_release_docs_versions.dart --release-prep in release automation. |
Review details
Suppressed comments (1)
tool/testing/verify_release_docs_versions.dart:288
- _matchInFile() uses readAsStringSync() without handling FileSystemException; this can crash the tool rather than emitting a structured error (similar to _readLines).
final match = pattern.firstMatch(file.readAsStringSync());
if (match == null) {
errors.add('$path does not contain its $what.');
return null;
- Files reviewed: 17/18 changed files
- Comments generated: 3
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
🟡 Changes recommended
tool/testing/check_webgpu_bridge_tag.dart still has uncaught FileSystemException paths (sync reads) that can crash the gate instead of reporting actionable errors.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (1)
tool/testing/check_webgpu_bridge_tag.dart:271
- findBridgeRuntimeDrift reads the pinned docs with readAsStringSync() without handling FileSystemException; an unreadable doc file will crash the gate instead of reporting a problem and continuing to check other pins.
final matches = pin.pattern.allMatches(doc.readAsStringSync()).toList();
- Files reviewed: 17/18 changed files
- Comments generated: 1
- Review effort level: Lite
There was a problem hiding this comment.
🟢 Approval recommended
The changes are well-scoped to release gating/docs alignment, include targeted tool hardening and unit coverage, and only leave a minor naming-clarity nit.
Review details
Suppressed comments (1)
Previously missed (1) — in code that hasn't changed since the last review.
tool/testing/check_webgpu_bridge_tag.dart:238
- The parameter name
bridgeTaginfindBridgeRuntimeDriftis ambiguous here because it actually represents the bridge assets’ embedded llama.cpp build tag (e.g.b10514), not the bridge asset release tag (e.g.v0.1.37). Clarifying this in the doc comment would make future updates less error-prone.
/// Returns one message per problem with the Web/native llama.cpp relationship.
///
/// `hook/build.dart` and the bridge manifest move in different repositories, so
/// nothing else notices when a native pin bump silently ends Web/native parity
/// and leaves the docs claiming it.
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🟢 Approval recommended
The changes are well-scoped to release gating/docs/version alignment, add targeted unit coverage for the new failure modes, and align CI/workflow checks with the stricter release-prep requirements.
Review details
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
…0-8-21 # Conflicts: # CHANGELOG.md # website/docs/changelog/recent-releases.md
There was a problem hiding this comment.
🟢 Approval recommended
The changes align docs, companion versions, and release gates, and they’re backed by targeted unit tests and stricter CI enforcement without altering runtime behavior.
Review details
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🟢 Approval recommended
The changes are consistent with the stated release-prep acceptance criteria and are backed by targeted unit tests plus updated CI/release workflow wiring.
Review details
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🔵 Needs a closer look
tool/testing/verify_release_docs_versions.dart’s _matchInFile() doesn’t catch FormatException from readAsStringSync(), so UTF-8 decode failures can still crash the gate instead of producing an actionable error.
Review details
Suppressed comments (1)
tool/testing/verify_release_docs_versions.dart:308
- _matchInFile() only catches FileSystemException from readAsStringSync(), but File.readAsStringSync() can also throw FormatException on UTF-8 decode failures. This can crash the gate with a stack trace instead of surfacing an actionable error (and other readers in this file already handle FormatException).
late final String contents;
try {
contents = file.readAsStringSync();
} on FileSystemException catch (error) {
errors.add('$path could not be read: $error');
return null;
}
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🔵 Needs a closer look
The new Web/native runtime gate does not currently enforce that the docs switch back to parity wording when pins converge, so a future convergence could leave incorrect “trails” prose while the gate remains green.
Review details
Suppressed comments (1)
Previously missed (1) — in code that hasn't changed since the last review.
tool/testing/check_webgpu_bridge_tag.dart:265
- In findBridgeRuntimeDrift, when nativeTag == bridgeTag and divergence == null, the gate only validates that the pinned docs sentence still matches bridgeLlamaCppTagPins and quotes the tag, but it does not enforce that the docs describe parity (as opposed to still saying “now trails”). This means a future convergence could leave the docs incorrectly claiming Web trails native while the gate stays green.
final nativeTag = match.group(1)!;
if (nativeTag == bridgeTag) {
if (divergence != null) {
problems.add(
'bridgeLlamaCppDivergence records a divergence, but the bridge assets '
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🟢 Approval recommended
The changes are cohesive and low-risk (docs + release-prep tooling), and the new enforcement logic is covered by targeted unit tests and wired into the release workflow to prevent regressions.
Review details
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🟢 Approval recommended
The changes are internally consistent, add targeted gate hardening with unit coverage, and align docs/workflows with the stated release-prep requirements.
Review details
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🟢 Approval recommended
The changes are well-scoped, add enforcement + regression tests for the identified release blockers, and the updated gates correctly fail closed in the scenarios described.
Review details
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🔵 Needs a closer look
It modifies release automation gates and the release workflow itself, which warrants careful human review despite the added test coverage.
Review details
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🔵 Needs a closer look
It changes release automation and release-prep gates/workflow behavior, so it needs final human validation despite only a minor docs nit found.
Review details
Suppressed comments (1)
Previously missed (1) — in code that hasn't changed since the last review.
website/docs/platforms/webgpu-bridge.md:199
- The pronoun “They” here is ambiguous and can read as referring to “Web and native” (the previous sentence) rather than the bridge assets. Reword to explicitly attribute the stack provisioning to the bridge assets to avoid misdocumenting native behavior.
build. They provision an explicit 1 MiB stack for both wasm32 and memory64,
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🔵 Needs a closer look
It changes release automation gates and enforced cross-repo pin contracts, which are high-impact even with strong regression coverage.
Review details
- Files reviewed: 17/18 changed files
- Comments generated: 0 new
- Review effort level: Lite
What changed
Two release blockers for 0.8.21, plus the two gates that should have caught them.
B1 — the
b10545Apple pin could not publishpackages/llamadart_llama_cpp_flutter/darwin/.../Package.swiftandhook/build.dartboth moved tob10545after v0.8.20, but the companion stayedat
0.0.14— already live on pub.dev (curlreturns HTTP 200). ItsCHANGELOG recorded
b10545under## Unreleasedwhile## 0.0.14recordedb10514..github/workflows/release_on_prep_merge.ymlloops the companion paths and:so the companion would have been skipped silently and Apple builds would have
kept resolving
b10514.Fix, per
website/docs/maintainers/release-workflow.md§2 ("bump only companionpackages whose native pins … changed, move their accumulated
Unreleasednotesinto the new version section"): bump to
0.0.15, rename## Unreleasedto## 0.0.15, and move the three current install snippets to^0.0.15(
README.md,website/docs/getting-started/installation.md,packages/llamadart_llama_cpp_flutter/README.md).example/chat_app/pubspec.lockfollows from
prepare_workspace.llamadart_litert_lm_flutteris not bumped:Package.swiftpinsv0.16.0-native.2, its CHANGELOG head is## 0.0.10recordingleehack/litert-lm-native@v0.16.0-native.2, and its pubspec is0.0.10—already self-consistent, and the new gate passes it unchanged.
B2 — a Web/native parity claim that stopped being true
website/docs/platforms/webgpu-bridge.mdanddoc/webgpu_bridge.mdsaid thev0.1.37bridge assets embedb10514"matching the default native runtime".The manifest genuinely says
b10514:but
hook/build.dartpinsb10545, so only the parity half was false. Bothsentences now say the bridge build trails the native pin. The bridge pin is
unchanged.
docs_version_cut.ymlsnapshotswebsite/docson the release tag,so the false sentence would have been frozen permanently.
Gates
(a)
tool/testing/verify_release_docs_versions.dartcompared onlyhook/build.dartagainstPackage.swift— both agreed atb10545, which iswhy B1 passed. It now also checks each companion's
Package.swifttag againstthe tag recorded in the CHANGELOG section its
pubspec.yamlversion willpublish.
A pin still sitting in
## Unreleasedis the documented native-sync state(
sync_native_release_pins.py --bump-companion-versionsis opt-in, "Native syncPRs should leave this unset"), so that case is reported as a pending bump in
the default run and fails only under the new
--release-prepflag.release_on_prep_merge.ymlnow passes--release-prep, so an unresolved bumpaborts the release before any tag is pushed. A pin recorded in neither section
is a hard error in both modes.
(b)
tool/testing/check_webgpu_bridge_tag.dartnow compares the bridgemanifest's
llama_cpp_tagagainsthook/build.dart's_llamaCppTag.bridgeLlamaCppDivergencerecords a deliberate divergence; a record left behindafter the tags converge fails too, so the escape hatch cannot become permanent.
--verify-manifestre-reads the published manifest so the recorded value stayshonest without making the default run network-dependent. The two doc sentences
are registered pins, so a reworded parity claim fails instead of outliving the
pin it describes.
Proof both gates bite
Each fix reverted in a scratch copy (
rsyncof the worktree, then restored):(a) revert to the exact
origin/mainstate — pubspec0.0.14,## Unreleased, snippets^0.0.14:and with the
## Unreleasednote deleted (pin recorded nowhere), the defaultrun fails:
(b) four directions (
git ls-filesnoise from the non-repo scratch dir elided):Both are also covered by unit tests: 7 new cases in
test/unit/tooling/check_webgpu_bridge_tag_test.dartand a newtest/unit/tooling/verify_release_docs_companion_pins_test.dart(6 cases), eachincluding a "the checked-in repo is clean" case so the gates cannot pass
vacuously.
Out of scope
Runtime behavior is unchanged. The bridge asset pin (
v0.1.37) and the nativepin (
b10545) are not moved; only the docs describing their relationship, thecompanion version, and the two gates change.
Validation
Pinned SDK:
Flutter 3.47.1 • Dart 3.13.1.dart run tool/prepare_workspace.dartthengit status --porcelaindart analyzeNo issues found!dart format --output=none --set-exit-if-changed .Formatted 573 files (0 changed)dart test -p vm -j 1 --exclude-tags local-only+1706 ~77: All tests passed!dart run tool/testing/verify_release_docs_versions.dartdart run tool/testing/verify_release_docs_versions.dart --release-prepdart run tool/testing/check_webgpu_bridge_tag.dartdart run tool/testing/check_webgpu_bridge_tag.dart --verify-manifest./tool/docs/validate_links.shVerbatim:
The same
verify_release_docs_versions.dartrun onorigin/mainbefore any fixexits 0 — that is the blind spot this PR closes.
Closes #449
Closes #450
High-risk regression review