[leehack]

Note

Repinned to litert-lm-native v0.19.1-2. Step 4 requalification (#1824) passed on GCE and S24, and the independent audit passed at 73ecbb76. Head 0296fd58 adds one test-only fix from that audit, and the exact-head re-audit of 0296fd58 passed. It stays draft (not marked ready).

Summary

• Step 3 of #1824. The C API 1 client now reads litert-lm-native's litert_lm_native_in_process_litert_abi_version once, during runtime selection. On Linux x64/arm64 and Windows x64, createEmbeddingSession throws LlamaUnsupportedException before any native call unless the value is exactly 1. A missing export, 0, or any unknown value is refused. Contract: litert-lm-native docs/platform_strategy.md, litert-lm-native#115.
• Repin to v0.19.1-2 (owner 0b15fb34, upstream 7a03724c, C API 1.0.0 unchanged) with tool/native/sync_native_release_pins.py: hook tag, all eight bundle sha256s, companion Package.swift URLs/checksums, companion README/CHANGELOG, macOS prepare script. The library smoke admits v0.19.1-2 as a C API 1 inventory; packaged-runtime guidance in errors, docs, skills and both changelogs names v0.19.1-2.
• Root cause addressed: custom v0.19.0/v0.19.1 desktop runtimes expose the same C API 1.0.0 as v0.19.1-1, but they load a separate libLiteRt, and embedding engine creation crashes on them (#1367). Only the marker tells them apart.
• Apple and Android are unchanged in behavior. GPU is not gated: marker 1 does not establish GPU support (gpu_registry.cc fallback, litert-lm-native#113).

Production-readiness scope

• User-facing scope: Linux/Windows LiteRT-LM embeddings run on the bundled v0.19.1-2 runtime and refuse runtimes that do not report in-process LiteRT, instead of crashing during engine creation.
• Supported platforms/paths: Linux x64/arm64 and Windows x64 embeddings on runtimes reporting marker 1 (v0.19.1-2+). macOS/iOS/Android arm64 embeddings are unchanged.
• Unsupported or intentionally unavailable paths: Linux/Windows embeddings on v0.18.x, v0.19.0, v0.19.1 or v0.19.1-1 runtimes throw LlamaUnsupportedException, naming the capability, ABI, marker state and minimum v0.19.1-2. checkLoad opens no runtime and still reports them as supported, as documented.
• Out of scope / follow-ups: GCE requalification (step 4 of #1824) passed; see Matrix Evidence. Marker-based GPU gating is out of scope (litert-lm-native#113 items 1–2). S24 (resolved): in the v0.19.1-2 Android arm64 bundle only libLiteRtLm.so differs from v0.19.1-1 (bdab4d4a… -> 9a56e701…, the exported litert_lm_native_in_process_litert_abi_version), so it was requalified on S24 rather than admitted on binary identity. The full 20-case graph passed on Test Lab (matrix-wmalbq6nz437a, see Matrix Evidence), and s24LiteRtRuntimeTags now admits v0.19.1-2 (3dd5356d; evidence recorded in 73ecbb76: doc comment, native/android_litert/README.md, doc/litert_lm_v1_adoption.md; the test's reject list moves to v0.19.1-3).

Completeness checklist

• Declared scope is fully implemented, or explicitly reduced above. (repin and step 4 requalification done)
• Unsupported platform/option combinations fail loudly with actionable diagnostics or are clearly documented as unavailable.
• Public API docs, README/website docs, examples, support matrices, and changelog entries are updated where relevant. (README pin table, support matrix, native build hooks, known-platform-issues, embeddings guide, maintainer sync doc, doc/ adoption and embeddings notes, both changelogs, llamadart-embeddings / llamadart-getting-started / llamadart-speech skills)
• Regression coverage covers the original issue plus key negative/version-skew paths where relevant.
• Public capability changes update the validation coverage registry with a pack or a reasoned, issue-linked exemption; inventory checks pass. (embeddings pack note updated)
• Security/privacy review completed: no secrets, bearer tokens, signed URLs, or raw secret-bearing paths leak through logs, cache keys, metadata, errors, or snapshots.
• Follow-up work that is useful but not required for this PR is tracked in GitHub Issues, or explicitly marked "None" above.

PR type guidance

• Bugfix PR: Root cause is described above. The tests compile the C API 1 embedding fixture with a configurable marker, plus a variant that omits the export. They cover marker 1 (created), missing/0/2/-1 refused on each Linux/Windows ABI with zero native embedding calls, entries and objects, a directly constructed client without a marker refused, and Apple/Android created without a marker or with 0. A probe unit test covers null/0/1/2.
• Feature PR / Docs-only PR: N/A.

Test Plan

At 2a206d89 (merge of origin/main at b78008cf plus the repin), macOS arm64, Flutter 3.47.1, isolated TMPDIR:

• dart run tool/prepare_workspace.dart (no tracked changes after commit)
• dart format --output=none --set-exit-if-changed .
• dart analyze (no issues)
• dart run tool/testing/check_platform_boundaries.dart
• dart test -p vm -j 1 --exclude-tags local-only test/unit/backends/litert_lm/ test/unit/hook test/unit/tooling/ test/unit/platform/io/runtime_setup_report_io_test.dart: 3605 pass, 5 skipped, 6 fail, all windows_registry_qualification_test (needs pwsh, not installed locally; CI runs it).
• python3 tool/native/test_sync_native_release_pins.py, test_native_header_archive.py, test_sync_native_headers_and_bindings.py, test_sync_stable_diffusion_bindings.py: OK.
• dart run tool/testing/check_native_release_digests.dart: liteRtLmBundleSpecs matches v0.19.1-2 release asset digests (8 bundles).
• dart test -p vm -j 1 --exclude-tags local-only (full): CI green at 0296fd58; locally at 73ecbb76 as part of coverage-lib below.
• dart test -p chrome --exclude-tags local-only: CI green (no Web code changed).
• coverage-lib at 73ecbb76: see Matrix Evidence.
• Host selection: dart tool/ci/test_shards.dart hosts reports every changed root test as "every OS". All eight ran and passed in CI's Test Native macOS (3 shards) and Windows (runtime 2/2, tooling) jobs.
• Real runtime marker check (macOS arm64): the production probe readLiteRtLmInProcessLiteRtAbiVersion on the hook-fetched v0.19.1-2 libLiteRtLm.dylib returns 1; on the cached v0.19.1-1 dylib it returns null (export missing). nm -gU shows _litert_lm_native_in_process_litert_abi_version only in v0.19.1-2.
• litert-lm-multimodal-embedding on macOS arm64 against the hook-fetched v0.19.1-2 bundle, EmbeddingGemma-2 e7a8a220…7f4c, CPU: 3/3 pass (control; macOS is not gated).
• At 0296fd58 (audit P3 fix: the E2E's LITERT_LM_V1_LIBRARY candidate route now passes readLiteRtLmInProcessLiteRtAbiVersion(library), so Linux and Windows no longer always refuse it): --dry-run, then the same scenario through the candidate route with LITERT_LM_V1_LIBRARY = hook-fetched v0.19.1-2 libLiteRtLm.dylib 5054e7f2…: 3/3 pass. Control: a wrong LITERT_LM_V1_LIBRARY_SHA256 fails setUpAll, which shows the candidate route is the one being exercised. dart format and dart analyze clean.

Mutation checks (at 56fd9261, before the repin; the gate code is unchanged since). Each mutation was applied alone, then reverted:

Mutation	Tests failing
Drop the gate call in createEmbeddingSession	15
Accept any non-null marker	9
Accept a missing marker	6
Accept marker >= 1	3
Gate every ABI (Apple/Android too)	29
Skip the Windows x64 gate	5
Skip the Linux arm64 gate	7
Facade does not pass the probed marker	12
Probe always returns 1	10
Probe returns 0 for a missing export	4

Matrix Evidence

Matrix row	Scope covered	Platform / model / backend	Result	Evidence / notes
owner release readback	tag, assets, digests	v0.19.1-2, 8 platforms	PASS	Prerelease, 21 assets, tag -> 0b15fb34; manifest schema 2, upstream 7a03724c, owner 0b15fb34; the 8 hook sha256 pins equal the GitHub asset digests (check_native_release_digests.dart) and the 7 Package.swift checksums match them (scripted comparison); hook download of the macOS bundle verified against its pin
high-risk-exact-head-independent-qa	independent blocking-only review of exact head/current base	73ecbb76, re-audit 0296fd58 / b78008cf3	PASS	Fresh agent session, not the author: no P1/P2. 8/8 hook digests and 7/7 Package.swift checksums verified, 8/9 gate mutations killed, merge-tree with main ec4bf4f89 clean. One P3 (E2E candidate route lacked the marker) is fixed in 0296fd58, test-only; the exact-head re-audit of 0296fd58 passed (test-only delta correct, merge-tree with main ec4bf4f89 clean)
coverage-lib	lib line coverage, 70% threshold	macOS arm64, 73ecbb76	PASS	dart test -p vm -j 1 --exclude-tags local-only --coverage=coverage (+11616 ~129 -6; the 6 are windows_registry_qualification_test, which needs pwsh), then format_lcov.dart --report-on=lib --check-ignore and check_lcov_threshold.dart: 93.63% (33221/35482) vs 70%. New gate code fully covered: liteRtLmEnsureInProcessLiteRtForNativeEmbeddings 6/6 lines, readLiteRtLmInProcessLiteRtAbiVersion 3/3, facade marker wiring 3/3, v1 client marker field and gate call 6/6. 0296fd58 changes only a local-only E2E
release-metadata-verification	core-patch metadata		N/A	No release metadata changes
structured-output-adversarial	structured output		N/A	No parser, grammar or structured-output changes
litert-lm-multimodal-embedding	text/image/audio/mixed/batch	macOS arm64, EmbeddingGemma-2, CPU, v0.19.1-2	PASS 3/3	Control only
litert-lm-multimodal-embedding	same, through the marker gate	Linux arm64, Linux x64, Windows x64 (GCE), v0.19.1-2	PASS 3/3 per host	Head 2a206d89 (later commits only touch docs and the validation package). marker=1 on all three. Vectors bit-identical to the #1808 v0.19.1-1 run. Archives c01d608c… / 36017186… / dd250677… equal the pins. Negative control: v0.19.1-1 via LLAMADART_LITERT_LM_LIB_DIR gives marker=null and is refused with LlamaUnsupportedException. results
Qwen3 GPU/CPU generation	#1795 regression on the new binaries	Linux x64 + L4 Vulkan, Windows x64 + L4 D3D12, Qwen3-0.6B 555579ff…	PASS: GPU 3/3, CPU 2/2 on both	Head 2a206d89. NVIDIA L4 selected (Vulkan / Direct3D 12), 0 Dawn validation lines. Outputs byte-identical to the #1808 runs. Archives linux-x64 360171860fac…4d5d, windows-x64 dd25067751cb…0f83 (litert-lm-native#113 item 5). results
litert-lm-v1-public-direct	public direct dispatch, uninjected LiteRtLmRuntimeClient, hash-bound runtime/model/config, 2 engine lifetimes, cancel and reuse	macOS arm64 / Qwen3-0.6B c5f39b41… / CPU / hook-fetched v0.19.1-2	PASS	receipt passed: true, qualified_public_v1: true, source 73ecbb76 (tree 3581608d, unchanged), 7-payload manifest fce579e6… (every dylib matches the owner SHA256SUMS), core 5054e7f2…, profile chat-litert-cpu.json 0f3ea7ad…; native finish stop/stop/cancelled, all settled
litert-lm-v1-public-service	public service dispatch, uninjected default LiteRtLmService, same bindings	macOS arm64 / Qwen3-0.6B / CPU / v0.19.1-2	PASS	receipt passed: true, qualified_public_v1: true, source 73ecbb76, same manifest/core/profile hashes; cancel settled (the service exposes no cancelled native-finish getter, as documented)
litert-lm-v1-public-speech	public speech dispatch		N/A	Speech path unchanged
litert-lm-json-schema	JSON Schema enforcement		N/A	Unchanged
S24 LiteRT qualifier (20-case graph)	native launch/GPU guard/CPU/GPU controls, public legacy GPU refusal, public CPU, legacy auto, corrected auto (2 lifetimes each, cancel, reload)	Galaxy S24 SC-51E / API 36 (Test Lab), Qwen3 0.6B CPU c5f39b41… + GPU 555579ff…, v0.19.1-2	PASS 20/20	matrix-wmalbq6nz437a, run pr1830-litert0191-2-s24-20261108, one 20-min execution, no retries; source 3dd5356d, binding 32a53c56…, app APK a27b57ec…. Android arm64 archive 1b72d7f6… (= hook pin); APK libraries byte-identical to it, incl. libLiteRtLm.so 9a56e701…; other five owner libs unchanged from v0.19.1. Completion present, 0 failed / 0 unexecuted, 6 lifetimes closed; unchanged decode_s24.py accepted journal a71fb3b3… (523 records, 259 captures) + 15 extracted sidecars. Native GPU and both corrected-auto lifetimes: OpenCL, full LITERT_CL delegation (1306/1306 decode, 1358/1358 prefill), no CPU fallback. Same four legacy semantic failures as v0.19.1 (matrix-1nd80qbdta8cf).

Review Notes

• Independent review status: PASS at 73ecbb76 (no P1/P2; P3s on #1837). The re-audit of exact head 0296fd58 also passed.
• CI status / head SHA: green, 37 pass, 9 skipping, 0 fail / 0296fd585eac2aa26f1b10a2e141560f33542d9e. Also green at 73ecbb76 (37/9/0). At 2a206d89 the only failure was the S24 tag test (validation-harness), fixed by admitting v0.19.1-2 after the S24 requalification.

High-risk regression review

• Classification: high-risk (surfaces: artifactConsumer, backendRuntime)
• Implementation task: #1824 step 3 implementation lane
• Independent blocking QA task: fresh-agent auditor sessions, not the author. Full audit PASS at 73ecbb76b1023c4dc749d112970a71f27bd9b113: no P1/P2, 8/8 hook digests and 7/7 Package.swift checksums, 8/9 gate mutations killed, P3s on #1837. Exact-head re-audit PASS at 0296fd585eac2aa26f1b10a2e141560f33542d9e: the test-only delta is correct.
• Exact head / current base: 0296fd585eac2aa26f1b10a2e141560f33542d9e / b78008cf31fbf6c967e1cc5bf2c557764c2072d3 (merge base; merge-tree with current main ec4bf4f89 clean at audit)
• Production-branch deletion, bypass, or miswire proof: Mutation table above, plus controls re-observed at 0296fd58 for every changed production path (readiness evidence below). Platform gate value, v1 client marker field and facade marker: each fails the 3 desktop creation cases. Dropping the gate call fails the 12 refusal cases. Probe returning 1 for a missing export, the base service message, each of the 3 pin files set back to v0.19.1-1, dropping v0.19.1-2 from the smoke inventory, a missing embeddings profile, and the base S24 tag set each fail their case.
• Affected-family real-model/artifact evidence: GCE at 2a206d89 (results): EmbeddingGemma-2 3/3 on Linux arm64/x64 and Windows x64 with marker=1, the v0.19.1-1 negative control refused, and L4 Qwen3 GPU 3/3 + CPU 2/2 on Linux Vulkan and Windows D3D12. S24 Test Lab matrix-wmalbq6nz437a 20/20 on v0.19.1-2. macOS arm64 at 73ecbb76: litert-lm-v1-public-direct and -service PASS, embedding control 3/3, candidate route 3/3 at 0296fd58. Commits after 2a206d89 change no runtime bytes.
• Explicit unavailable-family or other N/A evidence: Android x86_64 unchanged and unqualified; S24 requalified on v0.19.1-2 (Matrix Evidence)
• Known PR-caused P1 regressions: 0 known
• Readiness evidence: tool/testing/high_risk_readiness.dart on v2 evidence for head 0296fd58 / base b78008cf3 exits 2 (unverifiedPrerequisites / externalPrerequisitesUnavailable: internally consistent; auditor authentication, GitHub App, protected environment and ruleset are not configured, as documented). Required matrix rows: high-risk-exact-head-independent-qa only. 7 test records cover all 11 changed production paths; the registry record notes that no test asserts the notes text.
• Unresolved review threads: 0 (live GraphQL: 0 threads, 0 unresolved)

[leehack]

CI at 56fd9261f: 34 pass, 9 skipping, 0 failing. No CI job runs real-runtime LiteRT-LM desktop embeddings: the LiteRT-LM smokes on Ubuntu and Windows run chat and engine only, and multimodal_embedding_litert_e2e_test.dart is local-only. So the merge blocker (the bundled v0.19.1-1 lacks the marker, so desktop embeddings are refused) does not show up in CI. Still blocked on the repin to v0.19.1-2.

[leehack]

GCE requalification on v0.19.1-2: PASS (head 2a206d89780c9334095aa692fd2634a7a89e723b)

Step 4 of #1824. Every host checked out this head and ran prepare_workspace.dart, so the runtime is the hook-fetched v0.19.1-2 bundle. Each archive's sha256 equals its pin in native_release_pins.dart. No LLAMADART_LITERT_LM_LIB_DIR, no guard bypass.

The marker was read with the production readLiteRtLmInProcessLiteRtAbiVersion from the module that production runtime selection loaded: the /proc/self/maps path on Linux, GetModuleFileNameW on Windows.

Platform	Backend	Model (sha256)	Bundle archive sha256 / loaded libLiteRtLm sha256	Head	Result
Linux arm64, c4a-standard-8, Ubuntu 24.04	CPU embeddings	EmbeddingGemma-2 e7a8a2204b91e0f96e92960e84a09a89212e1633dcb7575a9bf3378b4df77f4c	c01d608cc1f332e090f96295c32019dd238b16cc194f29264aec950e92e511b5 / f70feea7c3b69cbbdc1631c5094a36b240f6d5fee4764b167a139ecb56292eb6	2a206d89	PASS: marker=1, C API 1.0.0; litert-lm-multimodal-embedding 3/3; probe vectors (2 passes) bit-identical to the #1808 v0.19.1-1 run
Linux x64, c3-standard-8, Ubuntu 24.04	CPU embeddings	EmbeddingGemma-2 (same)	360171860fac20057e107dbbe6fd1b1376d4011efe1bcf6ad7b8045ff13b4d5d / f5ca759025a1cc3b95c4b9166c17c2ea2e03611ef06c3c6b2a28c1f79d45634c	2a206d89	PASS: marker=1; E2E 3/3; vectors bit-identical to the #1808 run
Linux x64 (negative control)	CPU embeddings through LLAMADART_LITERT_LM_LIB_DIR = published v0.19.1-1	EmbeddingGemma-2 (same)	1c93ead8d8977b0b1e69d0054555881af16e2b6e46a584870ab86cd51c28589c / b8594f05746550156a79cd3785592d8a86eae854e2a82b632ba3c5e56df0f410	2a206d89	Refused as designed: marker=null (export missing). The model loads, then embedContent throws LlamaUnsupportedException ("… need LiteRT compiled into the runtime (in-process LiteRT ABI 1), and the loaded runtime does not export litert_lm_native_in_process_litert_abi_version …"). No crash
Windows x64, c3-standard-8, Server 2022	CPU embeddings	EmbeddingGemma-2 (same)	dd25067751cb9f42434e4f2b8dcdae725dd72b94f36ca5c359bb9b3616750f83 / LiteRtLm.dll 9effdc4f7f7a9028ac8a19f7e6cc41120b83861f18f0eda523090c18f6404222	2a206d89	PASS: marker=1; E2E 3/3; vectors bit-identical to the #1808 run; no WER dumps
Linux x64 + L4, g2-standard-8 (Spot, stockouts), driver 580.178.04	GPU (Vulkan) generation ×3, CPU ×2	Qwen3-0.6B 555579ff2f4fd13379abe69c1c3ab5200f7338bc92471557f1d6614a6e5ab0b4	360171860fac…4d5d / f5ca7590…634c	2a206d89	PASS: GPU 3/3 rc=0, Selected adapter: NVIDIA L4 … backend=Vulkan, adapterType=Discrete GPU, 0 Dawn validation lines; CPU 2/2. Outputs byte-identical to the #1808 v0.19.1-1 L4 run
Windows x64 + L4, g2-standard-8, driver 596.86	GPU (D3D12) generation ×3 (debug log), CPU ×2	Qwen3-0.6B (same)	dd250677…0f83 / 9effdc4f…4222	2a206d89	PASS: marker=1; GPU 3/3 rc=0, NVIDIA L4 … backend=Direct3D 12, 0 Dawn validation lines; CPU 2/2; no dumps. GPU output identical to Linux GPU and to the #1808 Windows run

Notes:

• LiteRT-LM desktop GPU crashes on Linux x64 and Windows x64 (v0.19.1) #1795 does not regress on the new binaries, and the marker gate admits the bundled runtime on all three desktop ABIs.
• Not run here: litert-lm-v1-public-direct / -service (they need the LITERT_LM_V1_* manifest and config inputs), the S24 binding, and the exact-head audit.
• If the head moves for a validation-package-only change (the S24 binding), no runtime bytes change, but the ready gate still needs these results recorded against the new head.
• Cleanup: all 5 VMs and the job bucket were deleted, and gcloud compute instances list is empty. No firewall rules were created; jobs ran through startup-script agents.

[leehack]

Landed via batch integration PR #1843 (rebase merge), one commit per constituent.

[github-actions]

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