Skip to content

Make SoundPackCatalog and HostIdentity host-configurable - #148

Merged
alexkroman merged 2 commits into
mainfrom
claude/blurt-identity-soundpack-e622pc
Aug 18, 2026
Merged

Make SoundPackCatalog and HostIdentity host-configurable#148
alexkroman merged 2 commits into
mainfrom
claude/blurt-identity-soundpack-e622pc

Conversation

@alexkroman

@alexkroman alexkroman commented Aug 18, 2026

Copy link
Copy Markdown
Collaborator

What & why

The engine previously shipped a hard-coded catalog of 192 cue voices and a single BlurtIdentity constant. This change makes both host-configurable:

SoundPackCatalog: Moved from the engine to the app target as a host-supplied value. The engine now ships no voices or audio files — only the SoundPack descriptor type and a SoundPackCatalog struct that hosts populate with their own voices. This fixes a design flaw where a package consumer got a picker full of silence (192 voices whose .m4a files weren't in their bundle). The voices and audio are one artifact (both generated by scripts/generate-sounds.swift), so they must ship together or not at all. Blurt's catalog now lives in App/Blurt/Blurt/SoundPackCatalog.swift alongside its audio resources.

HostIdentity: Replaced the BlurtIdentity enum with a configurable HostIdentity struct. This allows a host to override the Keychain service, logging subsystem, UserDefaults prefix, log directory, product name, and release feed — all from a single configure(_:) call at composition root. An unconfigured engine defaults to .blurt, preserving byte-for-byte compatibility. This eliminates the need for hosts to compose against custom APIKeyStore or logging facades just to use different Keychain/defaults namespaces.

Related changes:

  • SoundPackStore now takes a SoundPackCatalog parameter (the host's voices)
  • DefaultsKey raw values are now unprefixed; the host's defaultsPrefix is applied at read/write time
  • All engine components read HostIdentity.current instead of hard-coded constants
  • Updated scripts/generate-sounds.swift to emit the catalog to the app target
  • Removed BlurtIdentityTests (replaced by HostIdentityTests)

How it was tested

  • scripts/check.sh passes

  • Added HostIdentityTests covering the configurable identity and its defaults-key composition

  • Updated SoundPackTests and SoundPackCatalogTests to exercise the new catalog machinery against small fixtures

  • Updated SoundPackStoreTests to use a fixture catalog instead of the removed engine catalog

  • Updated DefaultsKeyTests to verify unprefixed raw values and prefix composition

  • Existing PersistedSettingsTests updated to account for the new structure

  • scripts/check.sh passes (or CI will, if I'm not on a Mac)

  • I read AGENTS.md and this doesn't reintroduce anything deliberately removed

  • Docs updated if behavior changed

https://claude.ai/code/session_01VbZNKdeyrVbn2cQtyBuFo8

@claude
Make the host's identity and cue catalog host-supplied
ed765f3 
The engine baked Blurt into six constants a third-party host inherited with
no opt-out, and shipped a 192-voice cue catalog whose audio lives only in
Blurt's app bundle. Both are now the host's to supply.

HostIdentity replaces BlurtIdentity as one value carrying the Keychain
service, the os_log subsystem (and the engine's queue labels), the
UserDefaults prefix, the ~/Library/Logs directory, the product name update
alerts say, and the release feed UpdateChecker reads. Every engine component
reads HostIdentity.current; a host overrides all six with one configure(_:)
at its composition root, or inherits .blurt by doing nothing — which is what
keeps this app byte-for-byte unchanged on disk. BlurtApp.init configures
.blurt explicitly, because the identity belongs to the host.

Process-wide rather than injected: the readers are static-let loggers, an
enum of defaults keys, and a Keychain facade — none of them things a caller
constructs. The derivations are pure functions of the value (defaultsKey,
logURL, queueLabel, logger), so the tests exercise them against a
constructed identity instead of mutating the shared one, which every suite
reads in parallel.

DefaultsKey raw values lose their "Blurt" prefix and gain `key`, the
identity's prefix plus the raw value — so Blurt still writes
BlurtSoundPack and a second embedder gets its own namespace instead of
writing into Blurt's slot.

SoundPack keeps only the descriptor; the new SoundPackCatalog is a
host-supplied value carrying the picker sections, the lookup and the
decode-with-default rule, and Blurt's 192 voices are generated into the app
target next to the .m4a cues they name. A catalog and its audio are one
artifact — a voice list whose stems name files in someone else's bundle is a
picker in which every choice plays silence, which is exactly what a package
consumer used to get. SoundPackStore stays engine-side so its key remains a
DefaultsKey case and cannot fall out of PersistedSettings.resetAll.

SoundPack.none is now installed after the voices, so a voice wrongly
claiming that reserved id loses its own slot rather than making "no sound"
unselectable — a host has no check.sh to catch the collision. check.sh's
catalog gate follows the file to the app target and also pins that
defaultVoiceID names a real voice, the failure mode the host-supplied
default introduces.

NOTE: App/Blurt/Blurt/SoundPackCatalog.swift is a new app-target source
file, so Blurt.xcodeproj needs `xcodegen generate` on a Mac before the
project-drift check can pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbZNKdeyrVbn2cQtyBuFo8
@alexkroman Claude

alexkroman commented Aug 18, 2026

Copy link
Copy Markdown
Collaborator Author

CI is red on exactly one step, and it needs a Mac — I can't fix it from this sandbox.

==> xcodegen (App/Blurt)
error: Blurt.xcodeproj/project.pbxproj is out of sync with project.yml; run 'xcodegen generate' and commit it

App/Blurt/Blurt/SoundPackCatalog.swift is a new app-target source file (the cue voices, moved out of the engine), and the .pbxproj references sources individually, so it has to be regenerated:

cd App/Blurt && xcodegen generate && git add Blurt.xcodeproj/project.pbxproj

project.yml is unchanged — sources: - path: Blurt already picks the file up — so this is purely mechanical. There's no route to it here: no Swift toolchain on this Linux runner (so no XcodeGen build), no brew/mint, the XcodeGen release API is 403 through the agent proxy, and protect-pbxproj.sh blocks hand-editing the file, which is the right call — the repo's rule is "edit project.yml and regenerate", not "write the pbxproj by hand". Worth noting the other option the engine README offered for this gap needs the same step, and more of it: moving the audio into the package would have deleted 384 app resource entries instead of adding one source file.

Green already:

  • compile — swift build --build-tests -Xswiftc -warnings-as-errors, so the engine and test targets typecheck with no warnings
  • swift test — 590 tests in 93 suites passed
  • format-patch — no diff, so swift-format has nothing to reflow
  • every source-only check in check.sh, which all run before swift test: swift-format lint --strict, swiftlint --strict, the settled-decision invariants, the sound-catalog gate (192 voices, both cues each, no orphans, default voice resolves), prettier, markdownlint, shellcheck, shfmt, actionlint, zizmor, ruff, pytest, site integrity, dependency guard
  • gate is derivative — it only mirrors check's conclusion

Still unverified, because check.sh is fail-fast from swift test onward and the xcodegen step aborts the rest: the app-target build, the ≥88% engine coverage gate, the TSan/ASan passes, swiftlint analyze, and periphery. I reviewed the app-side diff by hand for what those would catch — the new static lets in the app's SoundPackCatalog extension are read only from @MainActor contexts (SoundStepView, CueSoundPlayer.loadCurrentPack), and every logger's isolation is unchanged since only the initializer expression moved — but that's inspection, not a build. Re-run after the regeneration and I'll fix whatever those turn up.

One periphery risk worth naming in advance, since retain_public: false means public-but-app-unused fails --strict: HostIdentity.init(...) is public for hosts but the app only uses HostIdentity.blurt. TranscriptionContext.init is already public and app-unused on green CI, so I expect it to pass — flagging it so it isn't a surprise if it doesn't.

Generated by Claude Code

@alexkroman
alexkroman added this pull request to the merge queue Aug 18, 2026
Merged via the queue into main with commit 30625b4 Aug 18, 2026
10 checks passed
@alexkroman
alexkroman deleted the claude/blurt-identity-soundpack-e622pc branch August 18, 2026 18:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@alexkroman @claude @alexkroman-assembly