[leehack]

Summary

• Prepare core 0.17.0 with all three Apple companions at 0.17.0, per the 0.17.0 section of #922. A core minor re-releases every companion with the new core constraint.

  Package	From	To	llamadart constraint	SwiftPM pin
  llamadart	0.16.5	0.17.0	n/a	n/a
  llamadart_llama_cpp_flutter	0.16.0	0.17.0	>=0.16.0 <0.17.0 → >=0.17.0 <0.18.0	v0.7.0-3 (published 0.16.0 ships v0.7.0-2)
  llamadart_litert_lm_flutter	0.16.2	0.17.0	>=0.16.2 <0.17.0 → >=0.17.0 <0.18.0	v0.18.1-4 (unchanged)
  llamadart_stable_diffusion_flutter	0.16.0	0.17.0	>=0.16.0 <0.17.0 → >=0.17.0 <0.18.0	v0.3.0-1 (published 0.16.0 ships v0.3.0)
  genkit_llamadart	—	untouched	—	—
  llamadart_model_store	—	untouched (0.1.0, unpublished)	—	—

• Package.swift pins were already moved by #1476 and #1474; this PR changes no pin or checksum.

• Hook constants llamaCppAppleCompanionVersion and stableDiffusionAppleCompanionVersion move 0.16.1 → 0.17.0, the first companion releases pinning v0.7.0-3 and v0.3.0-1; native_release_pins_test.dart derives both from the companion changelogs. Core 0.17.0 lists no earlier llama.cpp or SD companion pins.

• The SD rejection test in build_hook_stable_diffusion_integration_test.dart hard-coded cores 0.16.0/0.16.1; it now takes its cores from the first pinning companion's minor, which the hook requires for the named release (it failed 2 cases after the constant moved).

• Changelogs: ## Unreleased becomes ## 0.17.0 in CHANGELOG.md and recent-releases.md, compacted from 55 to 36 bullets (list below). Released sections are byte-identical. Companion ## Unreleased notes become ## 0.17.0; the LiteRT-LM companion gets a 0.17.0 pairing entry.

• MIGRATION.md: the three Unreleased: sections become 0.16.x -> 0.17.0: upgrade guide (anchor 016x-to-0170-upgrade-guide) with an upgrade-together intro, and gain two subsections: llama.cpp v0.7.0-3 companion requirement, and the enable_thinking behavior change (#1465, #750). The SPI section from #1537 was checked against the LlamaBackend diff since v0.16.5: all seven moved members and both interfaces are covered; BackendModelParamsCheck → BackendLoadCheck was never exported, so it needs no entry. The upgrade checklist gets a 0.17.x section; the README table links the 0.17 guide.

• Install snippets and pairing prose describe the 0.17.0 set: README, installation.md, native-build-hooks.md, image-generation.md, speech-to-text.md, the image-generation and speech skills, the companion READMEs, and the maintainer companion handoff.

• Lock files: the three tracked path-dependency locks are regenerated; only the local core/companion versions change.

• No versioned docs snapshot: docs_version_cut.yml creates version-0.17.0 from the v0.17.0 tag.

Changelog compaction (55 → 36)

Every caveat, limitation, unsupported path, qualification clause and issue link is kept; a token diff of old vs new shows only the dropped bullet's identifiers missing.

Change	Old bullets	Result
Dropped	Private validation harness next_token_scoring pack (#1196)	The harness is unpublished, so users cannot observe it.
Merged	SPI break (#362) + loadMultimodalProjector LiteRT-LM refusal (#1541)	One SPI bullet.
Merged	llama.cpp v0.7.0-3 + hook contract 2 (both #812) + Linux arm64 CPU variant ranking (#1459, unnumbered)	One runtime bullet; "next companion release" now names 0.17.0.
Merged	checkLoad + early setModel LiteRT-LM rejection (both #861)	One bullet.
Merged	Boolean thinking kwarg override + template's own thinking setting (both #750)	One bullet.
Merged	Grammar after an open thought (#1465) + required call after an open thought on Cohere2 MoE/Nemotron 3 Nano/MiniCPM5/Hy3 (#1494, unnumbered)	One bullet; the unnumbered part stays a sentence after the link.
Merged	DeepSeek V3.1 forced-open thought + Hermes-style open thought (both #750)	One bullet.
Merged	Cohere2 thinking-off streaming (#1553, #1557) + Cohere2 thinking-off parse (#1566)	One bullet.
Merged	Cohere2 open-thought end + reasoning: true empty thought (both #1523)	One bullet.
Merged	Seed-OSS no-thought prompt (#1561) + opened-thought prompt (#1575, unnumbered)	One bullet.
Merged	Qwen3-Coder parallel calls (#1530) + Seed-OSS parallel calls (#1540)	One bullet.
Merged	ToolChoice.required grammars (#1577) + Firefunction v2 id (#1565)	One bullet.
Merged	Shared cache root (#1444) + read-only cache hit (#1484, unnumbered)	One bullet.
Merged	remove/prune/clear in-use (#1467) + overlap/Windows read-only (#1490) + .removal (#1507) + overlap/.REMOVAL part of #1522	One cache-removal bullet.
Merged	Override assets.json.absent and CUDA sidecar parts of #1490 + future-dated record part of #1506 + invalid assets.json part of #1522	One override bullet.
Merged	Cached bundle re-extraction (#1558) + archive lacking libraries (#1490) + SHA256SUMS pre-seed message (#1506)	One cached-bundle bullet.
Merged	ios-arm64-sim + ios-x64-sim load-failure names (both #1565)	One bullet.
Reworded	SD v0.3.0-1 bullet	"matching companion release" now names 0.17.0.
Unchanged	WebGPU bridge v0.1.76 bullet	Kept verbatim, as check_webgpu_bridge_tag.dart requires.

Bullets are reordered: breaking change, runtimes, additions, chat-template fixes, then state/cache/hook fixes.

What merging this PR does

Merging publishes. This PR carries the release-prep label (the branch name release/0.17.0 does not match the release/prep-X.Y.Z pattern, so the label is what selects it), modifies the root pubspec.yaml and touches nothing under packages/genkit_llamadart/, so release_on_prep_merge.yml runs on merge and:

1. Re-runs verify_release_docs_versions.dart --release-prep and companion_pub_preflight.dart; either failing stops it before any tag.
2. Pushes the core tag v0.17.0, which starts publish_pubdev.yml (publishes llamadart 0.17.0, then creates the GitHub Release) and docs_version_cut.yml (snapshots version-0.17.0 docs, restores an empty ## Unreleased, pushes to main; docs_pages.yml deploys).
3. Waits for llamadart 0.17.0 on pub.dev, then pushes llamadart_llama_cpp_flutter-v0.17.0, llamadart_litert_lm_flutter-v0.17.0 and llamadart_stable_diffusion_flutter-v0.17.0; each runs publish_companion_pubdev.yml.
4. The merge commit's ci.yml and laya_tetris_hf_static_deploy.yml redeploy the hosted chat app and Laya Tetris demos.

llamadart_model_store is not published: the preflight discovers only packages with darwin/<name>/Package.swift, the release workflow lists only the three Apple companions, and website/docs/maintainers/model-store-package.md says it has no release routing yet. pub.dev versions cannot be unpublished. Hold the merge until the release is approved.

Production-readiness scope

• User-facing scope: after merge, automation publishes core 0.17.0 and the three companions at 0.17.0. Flutter Apple apps then get llama.cpp v0.7.0-3 and SD v0.3.0-1 through SwiftPM.
• Supported platforms/paths: all core platforms; Apple SwiftPM through the three companions.
• Unsupported or intentionally unavailable paths:
  • Published 0.16.x companions do not resolve with core 0.17.0 (constraint <0.17.0); apps upgrade core and companions together, as MIGRATION.md says.
  • Git/path overrides that keep a 0.16.0 llama.cpp or SD companion fail with Incompatible Apple llama.cpp companion / Incompatible Apple stable_diffusion companion.
• Out of scope / follow-ups:
  • Genkit structured-output follow-up (#1574) and #1211 part 2 after core publishes, per #922. Genkit docs still name llamadart 0.16.1, which stays accurate for genkit_llamadart 3.5.0.
  • llamadart_model_store publication needs its own routing and approval; its lower-bound CI lane is added once llamadart 0.17.0 is on pub.dev (model-store-package.md).
  • choosing-an-api.md ("Checked on 2026-10-23", published 0.16.x) is left as a dated check; refresh it after publish.

Completeness checklist

• Declared scope is fully implemented, or explicitly reduced above.
• Unsupported platform/option combinations fail loudly with actionable diagnostics or are clearly documented as unavailable. Hook behavior is unchanged from #1474/#1476; docs and MIGRATION.md name the 0.17.0 upgrade target.
• Public API docs, README/website docs, examples, support matrices, and changelog entries are updated where relevant.
• Regression coverage covers the original issue plus key negative/version-skew paths where relevant. No runtime code change; the companion-floor check has a negative control (Test Plan), and the SD rejection test now follows the companion minor.
• Public capability changes update the validation coverage registry with a pack or a reasoned, issue-linked exemption; inventory checks pass (or N/A with scope). N/A: no capability change; validation_coverage_test.dart passes.
• Security/privacy review completed: version, docs and test text only; no secrets or signed URLs.
• Follow-up work that is useful but not required for this PR is tracked in GitHub Issues, or explicitly marked above.

PR type guidance

• Feature PR: N/A, release prep.
• Bugfix PR: N/A, release prep. The SD hook test fix is a release-prep consequence: it hard-coded 0.16.x cores.
• Docs-only PR: N/A. Versions and constraints change, merge publishes, and two hook constants change (llamaCppAppleCompanionVersion, stableDiffusionAppleCompanionVersion), used only in incompatible-companion error text.

Test Plan

Pinned Flutter 3.47.1, macOS arm64. Suites, gates and verifiers ran at d4bdfda29f5081b33d0438b2113a631650249646; a0662585121bbed459f823501d1c5d5c2b525f0d changes only the tool-result images bullet in both changelogs (bridge-tag check re-run: OK), and the Apple probes ran at a0662585121bbed459f823501d1c5d5c2b525f0d. 6b5d069a07800a88867fd90bf2fefa529bc71429 changes only text (docs, skill, one Dartdoc line and one exception message), so the probes were not rerun; at 6b5d069a07800a88867fd90bf2fefa529bc71429: format 0 changed, analyze no issues, dart test -p vm test/unit/tooling/ +1240 ~5 (includes package_skills_test), engine_capabilities_test, test/unit/core/template/, tool-result media/parts, llama.cpp and native backend tests +1855, build_site.sh 2992 pages with no broken internal links.

• dart run tool/prepare_workspace.dart: no tracked changes (worktree and fresh full clone).
• dart format --output=none --set-exit-if-changed .: 0 changed (1609 files).
• dart analyze: no issues.
• dart run tool/testing/check_platform_boundaries.dart: OK.
• TMPDIR=<isolated> dart test -p vm -j 1 --exclude-tags local-only: +9696 ~126, all passed.
• dart test -p chrome --exclude-tags local-only: +4117 ~1, all passed.
• Other targeted/local-only validation:
  • dart test -p vm test/unit/tooling/validation_coverage_test.dart: +13, all passed.
  • test/unit/hook/native_release_pins_test.dart + build_hook_stable_diffusion_integration_test.dart: +52, passed (the SD file failed 2 cases before the test fix).
  • check_webgpu_bridge_tag.dart: OK on the promoted ## 0.17.0 sections.
  • python3 tool/release/check_core_archive.py (fresh full clone, after workspace prep): passed, 1636 files staged.
  • ./tool/docs/build_site.sh: 2992 pages, no broken internal links.
  • dart run tool/release/companion_pub_preflight.dart: all three companions exist on pub.dev; no published version declares a different llamadart constraint.
  • Apple probe apps (direct, shared, workspace; all three 0.17.0 companions as path dependencies): macOS and iOS simulator runs pass GGUF, LiteRT-LM and SD probes (Matrix Evidence).
  • Companions (all three): flutter analyze no issues; flutter test passes (2, 4, 2); flutter pub publish --dry-run with the checkout override: 0 warnings, 1 expected override hint.
• Release docs verifier: the shared local clone is shallow, so both modes ran in a fresh full clone (not shallow, 164 tags) at this head.
  • Default: Release docs versions verified: llamadart 0.17.0, llamadart_llama_cpp_flutter 0.17.0, llamadart_litert_lm_flutter 0.17.0, llamadart_stable_diffusion_flutter 0.17.0; checkout llamadart-native v0.7.0-3. exit 0.
  • --release-prep: same line, exit 0.
  • Negative control: widening the llama.cpp and SD floors to >=0.16.0 fails --release-prep (exit 1), naming the minor-lockstep rule and cores v0.16.0–v0.16.5 whose hooks reject v0.7.0-3.

Matrix Evidence

Matrix row	Scope covered	Platform / model / backend	Result	Evidence / notes
static-format-analyze	format, analyzer, web/native import boundaries	macOS arm64	PASS	0 changed / no issues / OK
root-vm	native-safe VM suite	macOS arm64	PASS	+9696 ~126, all passed, isolated TMPDIR
root-chrome	browser-compatible suite	Chrome	PASS	+4117 ~1, all passed
coverage-lib	lib/ line coverage	CI	N/A (CI)	Only two string constants change in lib/; CI's coverage job gates it
release-metadata-verification	release-prep verifier and companion-pins regression test	fresh full clone	PASS	--release-prep exit 0; verify_release_docs_companion_pins_test passes in root-vm; floor negative control fails as expected
release-companion-pub-gate	companion pub.dev availability and constraints	pub.dev API	PASS (pre-merge)	0.17.0 of core and all three companions return 404, as expected; latest published companions are 0.16.0/0.16.2/0.16.0 with <0.17.0 constraints, so no collision. Automated-publishing admin settings need a maintainer login to check
release-representative-smokes	Apple probe apps: direct, shared-package and pub-workspace layouts, core and all three 0.17.0 companions as path dependencies	macOS 26 arm64 (M4 Max) app; iPhone 17 Pro simulator (arm64); stories15M GGUF, Qwen3.5-0.8B-VL LiteRT-LM, SD runtime probe	PASS	At a0662585121bbed459f823501d1c5d5c2b525f0d, all 3 layouts: pub get resolves 0.17.0 x4; macOS runs GGUF on Metal, LiteRT-LM on gpu, SD reports MTL0; iOS sim runs GGUF CPU, LiteRT-LM gpu, SD MTL0. A universal iOS sim build fails with the documented EXCLUDED_ARCHS message (as on 0bddcde0d and v0.16.5) and passes with x86_64 excluded. Evidence llamadart-evidence/release-0.17.0/apple-probes/. Android and broader model smokes: cross-platform QA on 0bddcde0d (#922)
android-release-device-pool	Firebase device pool	n/a	N/A	Paid opt-in run; covered by the Firebase S24/Xperia QA round on 0bddcde0d
genkit-release	Genkit release isolation	n/a	N/A	packages/genkit_llamadart untouched
structured-output-adversarial	structured output	n/a	N/A	No parser or grammar change; changelog text only
litert-lm-json-schema	LiteRT-LM schema enforcement	n/a	N/A	No LiteRT-LM change
high-risk-exact-head-independent-qa	independent blocking review of exact head	fresh auditor session, exact head dfb4121	PASS	CLEAR: CLEAR delta re-audit at dfb4121; evidence /opt/UnitySrc/personal/llama/llamadart-evidence/pr-1585/evidence-1585-dfb4121.json

Review Notes

• Independent review status: CLEAR at exact head dfb4121 by a fresh auditor session (0 P1, 0 P2).
• CI status / head SHA: head dfb4121dd98d96c200bdd0736e2d67c7d236b2ec, CI pending. Previous head 6b5d069a07800a88867fd90bf2fefa529bc71429 was green (CI run) and audited CLEAR; dfb4121dd changes only release-note and doc wording (audit P2-1, P2-2, P3-1): Vulkan Tesla T4 evidence for image placement (Place image modules on the CPU and cap image GPU memory #1551) and gpuDevices (T4 + lavapipe QA), and the Cache and hook follow-ups from #1510/#1514 audits #1522 cache bullet.
• Changelog union merge: turn union off (release-workflow.md, "Changelog merges") before any rebase or merge of this branch.
• Claims to check before publish (release notes cannot be edited):
  • Image placement (#806) keeps "Vulkan has no hardware evidence yet", matching the support matrix. #1551 recorded a partial Linux x64 Vulkan run on a Tesla T4 (placement assertions passed; the smoke re-run after its fix is pending), so the wording is conservative, not a missed qualification.
  • The tool-result images bullet now names what the #1462 smoke ran (Qwen3.5-0.8B weights, qwen3vl_merger projector, Qwen3-VL template, macOS CPU and Metal) instead of "qualified on Qwen3-VL". README, the tool-calling guide, the support matrix, the tool-calling skill, the toolResultMedia Dartdoc and the unsupported-format LlamaUnsupportedException message say the same; no test pins that message.

High-risk regression review

• Classification: high-risk (artifactConsumer, backendRuntime, structuredOutput)
• Implementation task: this PR's author session
• Independent blocking QA task: fresh auditor session, CLEAR, 0 known PR-caused P1, 0 unresolved threads
• Exact head / current base: dfb4121 / 44de155 (merge-tree clean)
• Production-branch deletion, bypass, or miswire proof: the --release-prep floor check fails with >=0.16.0 floors; native_release_pins_test fails if either companion constant does not match its companion changelog; the SD rejection test failed when its cores did not share the companion's minor.
• Affected-family real-model/artifact evidence: none new; runtime artifacts and Package.swift pins are unchanged from #1474/#1476.
• Explicit unavailable-family or other N/A evidence: no runtime code or pin changes in this PR.
• Known PR-caused P1 regressions: 0
• Unresolved review threads: 0

[github-actions]

Chat app preview removed for leehack/llamadart-chat-pr-1585.