feat(plugins): plugin system v1 + voice-driven meme generator (10-iteration spike, productionized)

[initcore0]

Ships the plugin system and the voice-driven meme generator from the
10-iteration spike in #243, brought to production quality.

Every behavior the owner tested in #243 is carried byte-identical. What
changed is everything around it: the build defaults, the developer-only
surfaces, the manifest contracts, CI, and the docs. #243 stays open for you to
close; nothing here is marked do-not-merge.

---

Provenance

The spike ran ten owner-tested rounds, each fixing something reported against a
running build — the confident-wrong-template fallback, the stuck spinner, the
day-long-uptime download failure, the four-items-became-two-captions bug, and
finally the voice-command route. The full iteration log, including the root
cause of each defect and what was deliberately not done, lives in #243 and
is worth keeping as the design record.

The spike branched from what is still main today, so this is a clean
carry — no rebase conflicts, and nothing had to be dropped or reworked to
land it.

---

What's in it

Plugin system

Pure rules in OpenWhispCore (all swift test-covered), IO and AppKit in the
app.

• PluginManifest — the host/plugin contract. Id validation is strict because
  the id becomes a path component under Application Support.
• PluginDiscovery — merges an ordered provider list; providers are passed
  in descending trust order and earlier wins, so a user-writable directory
  can never shadow a reviewed plugin. The compile-time registry is one entry in
  that list — the seam a real loader plugs into rather than replaces.
• PluginEnablement — default-off, with pruning.
• PluginHost / PluginsPane / menu-bar submenu — none of it on AppState.
• Three window seams: PluginWindowLifecycle, PluginDictationSink,
  PluginVoiceCommandSink.

The meme plugin

Three merged template providers (imgflip, memegen.link, and the user's own
imported library — the only one that works offline and in any language), scored
search over names and keywords, per-template caption slots, schema-constrained
decoding, a normalized box model where the preview IS the export, an
idempotent ticket-guarded state machine, a rebuildable URLSession, and a
bounded learned affinity.

Voice-command routing

With refine armed, an instruction starting with a manifest-declared phrase goes
to the plugin instead of the refine LLM. Both flows work: selection-as-material
and spoken-remainder-as-material. Matching is prefix-only, word-boundary, exact,
no fuzzy — a match redirects a dictation away from the user's editor, so a
false positive costs them text. Non-match, disabled plugin, or a window that
can't take it all fall through to the untouched normal refine.

---

What productionizing changed vs the spike

PLUGINS ships on by default

PLUGINS now defaults to 1, matching WHISPERKIT / PARAKEET / SPARKLE;
PLUGINS=0 is the lean escape hatch. Compiled in != enabled — plugins stay
disabled at runtime until you enable one per-plugin in the pane.

The source list moved into scripts/plugin-source-args.sh, shared by build.sh
and build-dmg.sh. build-dmg.sh is the release path and had no plugin
support at all in the spike — left alone, the shipped DMG would have been the
only build with an empty Plugins pane.

scripts/verify-plugins-binary.sh guards package.sh and build-dmg.sh the
way the WhisperKit/Parakeet guards do. Plugins live outside build.sh's
OpenWhisp/ glob, so a broken source list drops every one of them with no
compile error — the app builds and runs fine with an empty pane. Verified
non-vacuous: it fails on a PLUGINS=0 binary and skips when that was
intentional.

Developer surfaces compiled out of consumer builds

MemeTrace's emission and the launch-gated probes are now behind
OPENWHISP_INSTRUMENTATION — the gate LLMBenchRunner and LLMLabView already
use. An env var that opens a window and drives a generate is a fine debugging
tool and a poor thing to leave reachable in a signed, notarized app holding
Accessibility and microphone grants.

Verified in both directions rather than asserted: [MemeGen] appears 0 times
in a default binary's strings, 1 time with INSTRUMENTATION=1.

The pure line-builders stay compiled — they're swift test-covered and the core
target has no instrumentation define. Only the side effect is conditional.

scripts/meme-runtime-proof.sh was referenced by a doc comment but never
existed. It does now, mirroring the voice-command harness.

MAK-100 contracts — all additive, all forward-compatible

Contract	Status
clipboardAccess (bool, default false)	Wired, not just declared
destination (enum, default ownWindow)	cursor / outputTarget reserved + validated
appAffinity ([String])	Reserved router metadata
voiceTriggers	Already shipped in the spike

Clipboard is genuinely gated. The host reads the pasteboard only for a
plugin that declared it, and the check runs before the read — an undeclared
plugin causes no NSPasteboard access at all. The rule lives in the pure,
tested PluginInvocationContext rather than at the AppKit call site where a
forgotten if would be invisible. The pane discloses it beside the network
hosts. The meme plugin declines it deliberately (its Cmd-V import is for
template images, an explicit user action).

Reserved routes are refused honestly. A manifest declaring .cursor reports
.unsupportedDestination, stays valid and runnable, and effectiveDestination
falls back in one place — rather than silently doing something the author didn't
ask for. An unknown destination decodes to the default instead of throwing,
so a manifest written for a future host degrades rather than vanishing.

appAffinity is a hint, never a priority. A test pins that declaring it buys
no ranking advantage, because MAK-100's ~15-tool cap makes trigger surface a
host-arbitrated resource — a manifest must never self-assign priority, for the
same reason networkHosts is a label.

Docs

New docs/PLUGINS.md: architecture, full manifest schema reference, how to
write an in-repo plugin, the security/trust model, and — as a committed
roadmap rather than an open question — the path to hot-swappable.

Hot-swap roadmap. The shipping requirement is installing a plugin without
rebuilding. In order: (1) manifest/script-driven plugins first, because it's
cheapest and delivers install-without-rebuild on its own (ScriptPostProcessor
and ConfigPack are already this shape); (2) out-of-process executables
next, the only option with real isolation, reusing two precedents this app
already ships — helper binaries at Contents/Helpers/ and the Agent Bridge's
local-socket protocol; (3) WKWebView as an optional UI layer; (4) dylibs
permanently ruled out, per ROADMAP section 6, which this PR leaves exactly as
it was.

README gains a plugin line and a docs link, ARCHITECTURE gains the plugins/
row, and ROADMAP section 6 gains a status banner plus two table rows.

CI

Two jobs pin opposite sides of the same flag, which is the point:

• build-app is now pinned to PLUGINS=0. Without the flag it would have
  silently started building with plugins when the default flipped, and the
  lean escape hatch would have rotted untested.
• build-app-plugins (new) builds the default configuration users actually
  get, then runs the symbol verify. A green build is not evidence the plugins
  linked.

The nightly full-fat package.sh job picks up plugins and the new guard
automatically.

---

Testing

plugins/ compiles only into the app and sits outside the swift test
target, so the split matters. Which pure core covers what:

Behavior	Covered by
Manifest schema, validation, forward-compat decode	PluginManifest
Provider merge, precedence, trust ordering	PluginDiscovery
Enablement + pruning	PluginEnablement
Shortcut assignment + collisions	PluginKeyEquivalent
Voice trigger matching, negatives, enablement gating	PluginVoiceCommandRouter
Clipboard gate, reserved destinations, affinity-is-not-priority	PluginInvocationContext + PluginManifest
The captions-to-boxes decision	MemeCaptionSeeding
List extraction from a dictation	MemeCaptionExtraction
Ranked parsing, slot enforcement, schemas	MemeAI
Search scoring, prefilter, merge, dedup	MemeTemplateCatalog / MemeTemplateMatcher
Busy state, tickets, timeouts, transport-failure detection	MemeGenerationState
Cache staleness policy	MemeCatalogCache
Box geometry, slot layouts, shrink-to-fit	MemeCaptionLayout
Learned affinity + its caps	MemeTemplateAffinity

Verified none regressed to the app layer during the carry. The decision
logic the spike moved into core is still in core: MemeCaptionSeeding.resolve
still owns the whole captions-to-boxes decision and applyRanked is still a
call to it plus UI glue.

What remains app-layer and untestable by swift test: window lifecycle, the
network round-trip, AppKit rendering, and the async refit. Those are what the
two runtime-proof harnesses exist for.

Gates

• swift test — 2685 passing, 0 failures (2670 carried + 15 new contract tests)
• AppState ratchet — OK at 7024 / 7024
• ./build.sh (default, now with plugins) — pass
• PLUGINS=0 ./build.sh — pass
• lean WHISPERKIT=0 PARAKEET=0 SPARKLE=0 — pass
• lean + PLUGINS=0 (the CI lean job's exact config) — pass
• INSTRUMENTATION=1 ./build.sh — pass
• Zero warnings in any plugin-owned file (113 total on the PLUGINS=0 build vs 112 with plugins — the plugin sources add none)
• Instrumentation gate verified in both directions on real binaries
• Plugins verify guard proven non-vacuous

Not verified

Same honest caveat the spike carried: the Mac app can't be screenshotted in
this environment (the name resolves to the iOS bundle), so no UI was visually
confirmed, and no live LLM round-trip was run against this build. The runtime
proofs in #243 were run against the spike binary; the code they exercise is
carried unchanged here, but they were not re-run after the instrumentation
gating — re-running them now requires INSTRUMENTATION=1 ./build.sh, which is
the one behavioral change to that path.

🤖 Generated with Claude Code