fix(apple-fm): real on-device generation (programmatic schema) + dlopen packaging so npm arm64 never crashes on macOS <26

[junhoyeo]

The bug (in the just-merged #721)

The apple-fm summarizer never actually ran on-device — every session silently fell back to the Rust heuristic (fm_version: null). Found via live validation now that Apple Intelligence is enabled on the build machine.

Root cause: apple_fm.rs passed a plain JSON Schema string to FMLanguageModelSessionRespondWithSchemaFromJSON, but the vendored shim decodes that via JSONDecoder().decode(GenerationSchema.self, …), which expects Apple's private serialized GenerationSchema dialect, not standard JSON Schema. It threw NSCocoaErrorDomain:4865 before generation → callback status 255 → respond_one returned None → heuristic. (This is also why Apple's own shim tests build schemas programmatically via DynamicGenerationSchema, never via the FromJSON string path.)

The fix

Switch to the programmatic schema builder (FMGenerationSchemaCreate / FMGenerationSchemaPropertyCreate / FMGenerationSchemaPropertyAddAnyOfGuide / FMGenerationSchemaAddProperty) + FMLanguageModelSessionRespondWithSchema. Drop SCHEMA_JSON and the FromJSON path. The task_category / complexity enums are now constrained on-device via anyOf guides (with parse_summary/normalize_* still as the post-hoc safety net). Also: log a one-line warning on a non-zero FM status (no more fully-silent fallback), and report.rs now counts FM-generated vs heuristic summaries.

Live proof (macOS 26.2 / arm64, Apple Intelligence on)

cargo test --features apple-fm live_summarize_smoke -- --ignored --nocapture:

ses_live_1: "Enhance API Security with JWT Middleware"  category=feature   complexity=complex   fm_version=apple-fm-on-device
ses_live_2: "Fix null pointer crash on settings page"   category=bugfix    complexity=moderate  fm_version=apple-fm-on-device

Real model-generated titles/categories (not heuristic "Work on "), fm_version now correct. A #[ignore]d live_summarize_smoke test documents this path (skipped in CI).

Verified: default (cross-platform stub) build, --features apple-fm build, clippy, fmt all clean; non-ignored tests pass.

Deferred (left for follow-up — non-blocking)

Sequential per-session generation latency (no batching/progress yet); these are tracked but out of scope here.

🤖 Generated with Claude Code

---

Summary by cubic

Make apple-fm actually run on-device with a programmatic schema, and load libFoundationModels.dylib at runtime so the prebuilt Apple Silicon npm binary works on all macOS versions and cleanly falls back when Apple Intelligence isn’t available. Docs now note apple-fm ships in the arm64 binary; the report shows FM vs heuristic counts and groups sessions via deterministic title clustering.

• Bug Fixes

  • Build the output schema programmatically and call FMLanguageModelSessionRespondWithSchema; remove the JSON path that forced heuristic fallback. Enforce enums with anyOf.
  • Load libFoundationModels.dylib via dlopen (macOS ≥ 26 only); if missing/unavailable, degrade to the heuristic. Do not link FM/Swift into the binary. Stage the dylib next to the binary and include it in the npm artifact.
  • Release the +1 retained FMGeneratedContent in the callback to fix one-handle-per-generation leaks.
  • Truncate the first user message to 1000 chars.
  • Log non-zero FM statuses and timeouts; per-session fallback to the heuristic.
  • Don’t persist empty task-group labels from blank titles.

• New Features

  • Group apple-fm sessions by deterministic title clustering; label groups by the most frequent title.
  • Show per-batch progress for apple-fm (batch size 8).
  • Report prints “M via Apple FM, N heuristic” for apple-fm.

^{Written for commit 097ea7f. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
tokscale	Ignored	Preview	Jun 20, 2026 11:33pm

[cubic-dev-ai]

No issues found across 2 files

_{Re-trigger cubic}

[junhoyeo]

Added two report improvements on top of the schema fix (commit 368128d7), validated live on real data:

1. Real task grouping for the apple-fm backend. Previously run_task_grouping skipped for apple-fm (only claude/codex/gemini/kiro did LLM grouping), so the Task Group table collapsed by exact title — degenerate (51× identical rows + near-duplicate singletons). Now apple-fm uses a deterministic Rust-side title clustering (significant-token normalization + Jaccard ≥0.6 / ≥2 shared tokens), labeled by the representative title. Live before→after:

Add JWT auth middleware   (8 sessions)
  Add JWT auth middleware
  Enhance JWT auth middleware
  Implement JWT auth middleware
Analyze large session data  (2)
  Analyze large session data
  Analyze large token count session

Near-duplicate titles merge into one group; unrelated ones stay separate. (CLI backends keep their LLM grouping; semantic FM array-output grouping was deliberately avoided — fragile on a small on-device model.) Unit-tested.

2. Summarization progress for apple-fm. batch_size was payloads.len() → the per-batch Batch i/total indicator never fired (109 sequential on-device calls showed nothing until done). Now apple-fm uses batches of 8 so progress is visible; the final ✓ N summarized (X Apple FM, Y heuristic) line and counts are unchanged.

Note: the earlier-suspected --since/--until bug was reproduced and is not real (it correctly returns all entries; the one-off 0 was a cold-start wiki-population artifact).

Verified: default + --features apple-fm builds, clippy, fmt clean; clustering + existing tests pass; live report --week shows merged groups + progress.

[cubic-dev-ai]

2 issues found across 1 file (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>