[leehack]

Note

Stacked on #1907. Review only this PR's own commits; the merges bring in #1907 heads. CI runs through workflow_dispatch.

Summary

• Part of #174 (A2 of the scoping decision). Native LiteRT-LM strict responseFormat is now gated per host ABI and accelerator, not by a macOS-only check. A host is admitted only after a real-model run passes on it.

• Admitted:

  Host	Accelerators
  macOS arm64	CPU, GPU
  iOS arm64	CPU, GPU
  Android arm64	CPU
  Linux x64, Linux arm64, Windows x64	CPU

  Every other ABI or accelerator throws LlamaUnsupportedException before any native call. The message names the backend and the ABI, and lists the accelerators that are qualified there.

• The gate checks the loaded backend before any engine is created. That backend includes the deprecated LiteRtLmBackend(preferredBackend:) override. After the engine is created, the gate checks the backend that actually runs.

• The device scenario refuses a model URL that carries credentials, a query or a fragment.

• New device scenario chat-app-litert-json-schema (example/chat_app/integration_test/litert_lm_json_schema_e2e_test.dart), wired into run_local_e2e.dart and test_matrix.dart. It checks:

  • an adversarial control
  • a sentinel
  • the nested/array/$ref/anyOf/pattern contract
  • the typed contract refusal
  • Gemma 4 thinking, or the Qwen3 thinking refusal
  • a length cutoff inside a constrained string

  --model-path takes a device path or an http(s) URL that the app downloads.

Qualification

Host	Model	CPU	GPU
macOS arm64 (M-series)	Qwen3-0.6B c5f39b41…	PASS	PASS
macOS arm64	Gemma 4 E2B 18193810…	PASS	PASS
iOS 26.5 simulator (iPhone 17, arm64)	Qwen3-0.6B	PASS	PASS
iOS 26.5 simulator	Gemma 4 E2B	PASS (thinking 617 chars)	Engine creation fails: "Failed to modify graph with delegate". This is not a schema failure, and it is refused as LlamaUnsupportedException at load.
Android 16 emulator (Pixel 9 Pro, arm64)	Qwen3-0.6B	PASS	Not admitted: the emulator cannot create a GPU engine (Dawn on gfxstream Vulkan)
Android 16 emulator	Gemma 4 E2B	Not run: the 2.4 GB model does not fit the emulator's data partition	Not run
Linux arm64 (GCE c4a, Ubuntu 24.04)	Qwen3-0.6B / Gemma 4 E2B	PASS / PASS (thinking 617 chars)	Not tested
Linux x64 (GCE c3, Ubuntu 24.04)	Qwen3-0.6B / Gemma 4 E2B	PASS / PASS (thinking 596 chars)	Not run: L4 stockouts in every zone tried; a Spot L4 was created but deleted before the run finished
Windows x64 (GCE c3, Server 2022)	Qwen3-0.6B / Gemma 4 E2B	PASS / PASS (thinking 596 chars)	Not run
Linux arm64 (Docker ubuntu:24.04 on macOS; supplementary)	Qwen3-0.6B / Gemma 4 E2B	PASS / PASS	-

GCE runs used the litert-lm-json-schema scenario at 519673fd, a candidate with the same code plus Linux and Windows admitted; it differs from the final table only in also admitting their GPUs. The GPUs on Linux, Windows and Android stay refused.

Production-readiness scope

• User-facing scope: strict JSON Schema output with native LiteRT-LM on iOS arm64 (CPU, GPU) and on the Android arm64, Linux x64/arm64 and Windows x64 CPU, in addition to macOS arm64.

• Supported platforms/paths: as admitted above, with Qwen3 (canonical template) or Gemma 4 (bundle template) and the Widen native LiteRT-LM JSON Schema to Gemma 4, macOS GPU and the shared schema contract #1907 schema contract.

• Unsupported or intentionally unavailable paths: each throws LlamaUnsupportedException before generation:

  • Linux and Windows GPU
  • Android GPU
  • Android x64
  • macOS x64
  • NPU

  Web keeps its existing refusal.

• Out of scope / follow-ups:

  • L4 GPU runs on Linux x64 and Windows x64 (stockout).
  • A physical Android device run for the GPU and for Gemma 4.
  • A physical iPhone run to separate simulator limits from device limits for Gemma 4 GPU.
  • Undocumented glibc floor: the pinned v0.19.1-2 Linux arm64 runtime needs glibc 2.38 or newer. It fails to load on Ubuntu 22.04 with a clear error, but no doc states the floor.

Completeness checklist

• Declared scope is fully implemented, or explicitly reduced above. (reduced to the hosts with passing runs)
• 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, support matrix, generation guide, doc/litert_lm_templates.md, doc/testing_matrix.md, llamadart-chat-streaming skill, both changelogs)
• Public capability changes update the validation coverage registry with a pack or a reasoned, issue-linked exemption; inventory checks pass. (no new capability surface beyond Widen native LiteRT-LM JSON Schema to Gemma 4, macOS GPU and the shared schema contract #1907's entry; validation_coverage_test.dart passes)
• Regression coverage covers the original issue plus key negative/version-skew paths where relevant.
• 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

• Feature PR: platform matrix and refusal behavior are listed above. Unit tests pin the default table per ABI and accelerator; device and host e2e runs cover real models.
• Bugfix PR / Docs-only PR: N/A.

Test Plan

At 2e90b3ad, macOS arm64, Flutter 3.47.1, isolated TMPDIR:

• dart run tool/prepare_workspace.dart
• dart format --output=none --set-exit-if-changed .
• dart analyze (no issues)
• dart test -p vm -j 1 test/unit/backends/litert_lm/ test/unit/tooling/package_skills_test.dart test/unit/tooling/run_local_e2e_test.dart test/unit/tooling/validation_coverage_test.dart: 1771 pass, 1 skipped
• dart test -p vm -j 1 --exclude-tags local-only / Chrome: CI (workflow_dispatch)
• coverage-lib: 93.70% at the Widen native LiteRT-LM JSON Schema to Gemma 4, macOS GPU and the shared schema contract #1907 head; this PR adds only a const table, tests and docs.
• Mutant: re-adding linuxX64: {'cpu'} and androidArm64 GPU to the table fails the default-table tests.

Matrix Evidence

Matrix row	Scope covered	Platform / model / backend	Result	Evidence / notes
static-format-analyze	format, analyzer, boundaries	macOS arm64	PASS
chat-app-litert-json-schema	device enforcement, contract, refusal, thinking, cutoff	macOS arm64 Qwen3 CPU	PASS
chat-app-litert-json-schema	same	iOS 26.5 sim: Qwen3 CPU and GPU, Gemma 4 CPU	PASS 3/3	Gemma 4 GPU: engine creation refused (see above)
chat-app-litert-json-schema	same	Android 16 emulator arm64: Qwen3 CPU	PASS	GPU and Gemma 4: environment-limited (see above)
litert-lm-json-schema	host e2e	Linux arm64 Docker: Qwen3 and Gemma 4 CPU	PASS 2/2 (supplementary)	ubuntu:24.04 fe815609…, glibc 2.39
litert-lm-json-schema	host e2e	GCE Linux x64, Linux arm64, Windows x64 CPU; Qwen3 and Gemma 4	PASS 6/6	at 519673fd; GPU not run, so refused
high-risk-exact-head-independent-qa	independent audit		PENDING

Review Notes

• Independent review status: pending
• CI status / head SHA: bc5d9726, dispatched CI run pending
• Overlaps: none beyond Widen native LiteRT-LM JSON Schema to Gemma 4, macOS GPU and the shared schema contract #1907. No edits to template/stream parser, Apple hook, Package.swift, litert_lm_runtime.dart or the validation manifest.

High-risk regression review

• Classification: high-risk (backendRuntime, regressionPolicy, structuredOutput)
• Implementation task: llamadart 0.19.5 lane 6 (#1899)
• Independent blocking QA task: pending
• Exact head / current base: bc5d9726 / 18e3993f (Widen native LiteRT-LM JSON Schema to Gemma 4, macOS GPU and the shared schema contract #1907)
• Production-branch deletion, bypass, or miswire proof: the default-table tests fail when a host or accelerator is added to or dropped from the table
• Affected-family real-model/artifact evidence: the qualification table above
• Explicit unavailable-family or other N/A evidence: Linux and Windows GPU are refused (no L4 run). Android GPU and Gemma 4 on Android lack device evidence.
• Known PR-caused P1 regressions: 0
• Unresolved review threads: 0

[leehack]

Landed via batch integration PR #1912 (rebase merge, main 2cfb936). The integration audit passed at a9c7772, and this PR's audited head is recorded in #1912's constituent table.