[adiled]

hive/apple-fm: Apple's on-device model as a nurse

hives/apple-fm runs Apple's on-device foundation model (SystemLanguageModel.default, ~3B, 4096-token context) as a hum nurse: local, network-free, key-free. It advertises apple-3b-on-device.

This supersedes the Oct 18 apple-fm-worker prototype, which predates main's move from WorkerBee to Nurse (chunk/finish → unfurl/wilt, serve_worker → serve_nurse, signed bee entry, hive-install units, version lockstep) and could not compile against main. It is rebuilt on main, and hives/apple-fm-worker is removed.

Shape

• apple-fm-nurse (Rust, on hum-nest's serve_nurse) runs apple-fm-gen once per bloom. apple-fm-gen is a Swift bridge built from bridge/gen.swift, the only file in hum that imports an Apple framework. The Rust side holds no Apple symbols and builds anywhere; ./build refuses any host that isn't an Apple silicon Mac.
• How a prompt maps to Apple's API:
  • the system prompt becomes Apple's instructions
  • the graft becomes Apple's transcript; with no graft, the cell's own turns are used, so graft-less foragers keep their conversation
  • temperature/season/prune/seed become Apple's generation options; temperature: 0 samples greedily
  • frost (stop sequences) is held by the nurse, which kills the bridge at a stop
• Streaming: each unfurl carries only the new words, and the bloom wilts stop or max_tokens with Apple's token counts as nectar.
• Context window: the bridge keeps the newest turns that fit and holds the reply to the room left. The cell forgets the dropped turns, and the nurse logs apple-fm.trimmed.
• Availability gate: before nestling, the nurse probes the bridge.
  • Apple Intelligence off, or model still downloading: waits unnestled and re-probes.
  • Mac that can't run the model: exits 0, so the unit stays down.
  • Bridge that can't run: exits non-zero.
• Refusals and errors:
  • pollen → apple_fm_words_only; trellis → apple_fm_no_trellis
  • Apple's own errors → apple_fm_<reason>
  • a bridge that dies or goes silent → apple_fm_bridge_died

Bugs in the prototype, fixed

1. The bridge's stdout was never piped.
2. --probe was ignored by the Swift side, so the probe always reported "available".
3. Cumulative snapshots were sent as deltas.
4. A duplicate resolve_bridge broke non-mac builds.
5. The cell's exit sender was dropped at birth.
6. A cancel left the bridge running.
7. The graft never reached the model.
8. Error JSON broke on newlines.

Tests (cd hives/apple-fm && cargo test)

• 17 unit and cell tests against a stand-in bridge. They cover the request mapping, sampling, refusals, Frost across delta boundaries, history kept and overridden by graft, dropped turns forgotten, still/cancel killing the bridge, stops, max_tokens, and a bridge that errors, dies, lingers, or goes silent.
• 5 E2E tests through a real in-process humd:
  • a prompt unfurls and wilts back with nectar
  • a graft-less follow-up keeps the conversation
  • a cancel kills the bridge
  • a dormant nurse waits, then nestles when ready
  • an ineligible Mac exits 0
  • a missing bridge fails the unit
• 1 live test against Apple's model (./build && cargo test --test live -- --ignored): conversation memory, real streaming with no repeated text, stop sequence, max_tokens at exactly the season, a conversation longer than the context, and cancel.
• All green 5× in a row on an M5 Max running macOS 26.6.2.
• Clippy: 0 findings in the hive.

Verified on a live humd

Installed with hum hive ./hives/apple-fm install (orchd → launchd unit hum-apple-fm.apple-fm) and exercised through openai-server's /v1/chat/completions:

• system prompt
• multi-turn
• max_tokens → length
• stop
• SSE streaming
• a conversation past 4096 tokens
• a client disconnect killing the bridge immediately

Also checked against the real model:

• no rate-limiting when launchd runs it
• 8 concurrent prompts all succeed (the default maxCells)

Registered

• root Cargo.toml exclude list
• release.sh version lockstep (0.34.1)
• hives/README.md catalogue

Not in this PR

• Co-installation into the mac desktop bundle: the follow-up gate. Struck: there is no mac desktop bundle; after merge, apple-fm is a bundled hive any capable Mac installs with hum hive apple-fm install.
• Tools and trellis. FoundationModels supports both, but the bridge offers neither yet; the README says so.

Note: wire.yml builds no hives, so CI doesn't exercise this hive. The tests above were run locally.