AquaSynth/docs/dings-patch-identity-authority-map.md

Dings patch identity: authority map

Serves follow-up aqua-body:follow_up:aquasynth-dings-authority-map. Claims are from source at c0fe4ee (origin/main). Nothing was built or run; the one place behaviour is inferred rather than read is marked. Paths are repo-relative; Host = tools/AquaSynthDingsHost, Mcp = tools/AquaSynthDingsMcp.

Companion to docs/research/dings-playback-and-ogg-export.md, which describes the playback path and an export sketch. This note asks a narrower question: in the Dings path, what decides which sound "this patch" is, and how many places decide it.

What I counted

The follow-up says four owners. The source supports four places that decide a voice's identity, plus one place that names the same thing a second time without deciding, and one generated mirror:

#	Owner	Decides	Section
1	DingCatalog	the instrument id and the script that defines its sound	A
2	Host and daemon derivation	the daemon patchId, faustName, revision, session id and store file names	B
3	MCP AgentInstrumentRegistry	which instrument an agent session gets	C
4	tools/dings-voices	which voice a sender (agent localpart) gets, in a separate synth	D
-	Earcon Workshop IDENTITIES	reuses catalog instrument ids with its own parameters	E
-	tools/aqua-feel/lowered-dings	checked-in copy of #1, guarded by a test	E

The follow-up does not list its four, so this grouping is my reading. Someone who counted differently (for example splitting the daemon's session id from the store file name, or counting Earcon Workshop as a fifth) would get a different number from the same code. The grouping above follows who writes the key.

A. DingCatalog instrument id and script

• Where: src/AquaSynth.Dings/DingCatalog.cs:22-28 (four instruments), built by the private Instrument(...) at :48-50, which writes the Script string (an AquaSynth patch script, param path=...; voice wave=..., that FaustEmitter.EmitScript lowers to Faust; not Faust source) and fixes RootFrequency = 261.6256f for all four.
• Keys on: the instrument Id string (warm-bell, glass-chime, soft-triangle, muted-pluck), case-insensitive dictionary (:28). Events are a separate keyed dictionary (:9-20, nine ids) and are not voice identity.
• Lifetime: compiled in. Changing an entry means a new build of every consumer.
• Writer: whoever edits the file. ValidateCuration (:31-46) is the only gate.
• Readers: Host/DingsPlaybackHost.cs:66-67, Mcp/DingService.cs:9-10, Mcp/AgentInstrumentRegistry.cs:11, Mcp/DingTools.cs:28,31,49, tools/AquaLower/Program.cs:17, and the tests DingCatalogTests.
• Content hash: none. The id is a label; the script is the content. Nothing here says "this script, at this version".

B. Host and daemon derivation of the patch

The Host does not pass the catalog id through. It builds the daemon's identity fields itself, and the daemon builds more keys from them.

• Host/AquaDaemonClient.cs:20 per note: patchId = "dings." + instrument.Id, faustName = "dings_" + instrument.Id.Replace('-', '_'), revision = 1 (a literal), durationSeconds = 1.5f, controls["/ding/frequency"].
• src/AquaSynth.Faust/NativeFaustRuntime.cs:596-599: the compile key is SHA-256 of "{revision}\n{faustName}\n{script}". patchId is not in it. So two ids with the same name and script share a compile key; one id with an edited script gets a new key even though revision stays 1.
• src/AquaSynth.Faust/AquaSynthDaemonService.cs:1136: session id = StoreFileName.From(patchId) + "-" + compileKey[..12]. A recompile with the same session id disposes the old session (:366-376).
• src/AquaSynth.Core/StoreFileName.cs:26-54: the mapping from any id to a file name (ASCII letters, digits, -, _, . pass unchanged unless the id has an uppercase letter, a device stem, a trailing dot, is over 100 characters or already ends in a hash shape; anything else gets a 16-hex SHA-256 suffix, StoreFileName.cs:37,59-67). dings.warm-bell is a fixed point (pinned by StoreFileNameTests).
• Keyed by patch: the session document. WriteReceiptAsync("sessions", sessionId, session) (:407) runs on every compile, and SampleAsync compiles on every note (:622-635), so the store holds sessions/<StoreFileName(sessionId)>.cc for each distinct (patchId, compile key), rewritten on each note. This is the one store artifact addressable by instrument. NativeFaustRuntime.cs:516,628-636 would also write <StoreFileName(patchId)>.dsp, but only when options.DspSourceDirectory is set; the daemon builds its native options from sample rate and render limits only (AquaSynthDaemonService.cs:330-334) and nothing else in src or tools sets it, so for the Dings host it is off. (Read from source, not observed.)
• Not keyed by patch: render output and the render and compile receipts. Samples are <store>/samples/<StoreFileName(commandId + "-render")>.wav (:664-667), where commandId is a fresh ding-<guid> per note (AquaDaemonClient.cs:19). Receipts go through WriteReceiptAsync (:922-937) under command-derived ids, with the patch id only in the body. The store therefore keeps one WAV per note played, none addressable by instrument. Whether the store ever gets cleaned I did not find.
• Faust name, three forms: the Host sends dings_<id with - as _>; the daemon applies SafeFaustName (NativeFaustRuntime.cs:602-607, called at AquaSynthDaemonService.cs:911 and NativeFaustRuntime.cs:513) so the manifest and emitted source carry the rewritten name, while the compile key (:596-599) hashes the raw identity.FaustName. Two raw names that sanitise alike compile alike but key differently.
• The dings_<id> rule is written three times: AquaDaemonClient.cs:20 and tools/AquaLower/Program.cs:19, and DingCatalogTests.cs:45 (LoweredDingsFedToTheFeelMeterMatchTheCatalog builds the name with the same expression). Nothing ties the three together except the test.
• Writer: the Host (fields) and the daemon (session id, file names). Readers: the daemon's compile/render path and receipts; no Dings code reads the patch id back.
• Host/AquaDaemonClient.cs:23-28 returns the WAV path from the receipt. The Host never asks the daemon which patch rendered it.

C. MCP AgentInstrumentRegistry

• Where: Mcp/AgentInstrumentRegistry.cs:10 (dictionary), :13-17 GetOrAssign, :19-29 Claim, :31-36 AssignDeterministically.
• Keys on: agentSessionId, which is server.SessionId ?? "stdio:" + ProcessId (Mcp/DingTools.cs:45; that SessionId is null under stdio is inferred from the ?? fallback, not read from the SDK). That is the MCP transport session, not the agent. In HTTP mode (Mcp/Program.cs:34-54, Stateless = false) it lives as long as that MCP session; in stdio mode it is the bridge process id.
• Value: an instrument id string. Unclaimed sessions get SHA256(sessionId)[0..4] % sortedInstrumentIds.Length. Claim overwrites silently, and there is no uniqueness check, so two sessions can hold the same instrument.
• Lifetime: in-process, a ConcurrentDictionary. Lost on bridge restart. A restarted or reconnected session gets a different session id, hence generally a different hashed instrument unless it claims again. (Inferred from the keying; I did not observe a reconnect.)
• Writer: the agent, through claim_instrument, or the hash. Reader: play_ding (DingTools.cs:16) and get_agent_instrument (:19).
• Also decides: DingService.PlayAsync (Mcp/DingService.cs:9-11) re-validates event, instrument and gain, and the Host validates the same three again (DingsPlaybackHost.cs:66-68). Two gates on one decision; they agree today because both read DingCatalog.

D. tools/dings-voices sender voices

• Where: tools/dings-voices/src/voices.mjs:8 (SENDERS, eight localparts), :51-73 (VOICES, one hit function each), :13-18 (RHYTHM, four motifs).
• Keys on: sender localpart x motif (mention, dm, message, invite), emitted as senders/<sender>/<motif>.ogg and manifest.json (finish.py:62, shape {neutral, senders:{localpart:{motif:path}}}).
• It does not use DingCatalog, AquaSynthDaemon or Faust. It is a JS synthesizer that imports only the sample rate from earcon-workshop/web/earcon.js (voices.mjs:5). Its vocabulary (4 motifs, 8 senders) shares no ids with Aqua's (9 events, 4 instruments).
• One link to the catalog family: the neutral fallback is rendered through the Earcon Workshop warm-bell identity (build.mjs:10-14), with an event mapping of mention=warning, dm=waiting, message=message, invite=done (:12) that the file itself calls provisional.
• Lifetime: a build artifact. The files are not committed (README, "Not here"); the consumer, Ratatoskr's dings.ts, is outside this repo and I did not read it.
• Writer: a person editing voices.mjs; NIBU_PROPOSALS (:81-92) shows the selection of the default voice is a one-line assignment (VOICES.nibu = ..., :92).
• This is the only place a sender is identity. Everything else in the Dings path keys on an MCP session.

E. Places that echo the identity without deciding it

• Earcon Workshop IDENTITIES, tools/earcon-workshop/web/earcon.js:22-27. Same four ids; its comment (:21) says values "start from the Dings catalog instruments and were not tuned by ear". The values have drifted from the catalog:

  id	catalog root / decay (DingCatalog.cs:24-27)	workshop rootHz / decay
  warm-bell	261.6256 / 1.15	261.6256 / 0.55
  glass-chime	261.6256 / 0.85	329.6276 / 0.45
  muted-pluck	261.6256 / 0.34	293.6648 / 0.25

  Decay is read with different units in the two voice models, so only the root column is a clean disagreement. A "warm-bell" in the Ratatoskr neutral fallback is therefore not the "warm-bell" an MCP agent hears.

• tools/aqua-feel/lowered-dings/ (checked in): .dsp per instrument and dings.json, produced by AquaLower --dings. DingCatalogTests fails when it falls out of date (the test comment at the top of LoweredDingsFedToTheFeelMeterMatchTheCatalog names the regeneration command). A mirror guarded by a test; not an independent owner. tools/aqua-feel/shelf.mjs:64 and catalog.js:22-24 read it, and shelf.mjs:64 defines warm-bell as the shelf default (DEF_INS, used at :71,:75,:76), a fifth voice default beyond the registry's hash.

Where owners can disagree

1. Name versus content. A is a name plus a script. B keys sessions on the content (compile key) and labels receipts with the name. Editing a script in place keeps patchId = dings.warm-bell and revision = 1, so receipts from before and after the edit carry the same patch id and different session ids. Nothing in a receipt says which catalog version produced it.
2. Session versus agent. C assigns by MCP session; the stated intent in Mcp/README.md:3-4 is "which agent spoke". After a reconnect the same agent can change timbre. D, meanwhile, keys on the agent address localpart. No code maps a session id to a localpart, so the two cannot be joined today.
3. Four timbres versus eight senders. C picks among 4 catalog instruments by hash; D has 8 hand-made voices. An agent can have one voice in play_ding and a different one in its Ratatoskr notification, and nothing records either choice.
4. Same id, different sound. warm-bell is a catalog instrument (A), a workshop identity (E) and the neutral fallback voice (D). Three definitions, parameter sets that have drifted (table above).
5. Derivation written three times. dings_<id> in AquaDaemonClient.cs:20, AquaLower/Program.cs:19, and the test; and the dings.<id> patch id appears in StoreFileNameTests as a literal. A rename rule changed in one place breaks store-file naming in another without a compile error.
6. Double validation. DingService.cs:9-11 and DingsPlaybackHost.cs:66-68 each decide whether an id is valid. Safe while both read one dictionary.

The Host pipe protocol, as read from source

This is the "private pipe": the only channel into the audio host. MCP is a client of it; it is not itself the pipe.

Listener. AquaSynthDingsHost.exe. Host/Program.cs:3-4 takes the named mutex Local\GameCult.AquaSynthDings.Playback.v1 and exits if another instance holds it, then runs DingsPlaybackHost.RunAsync (:7). The accept loop is DingsPlaybackHost.cs:12-20: one NamedPipeServerStream per accepted client, name GameCult.AquaSynthDings.Playback.v1 (src/AquaSynth.Dings/DingsProtocol.cs:8), PipeDirection.InOut, byte mode, MaxAllowedServerInstances, Asynchronous | CurrentUserOnly (:16). Each connection is handled fire-and-forget (:18). The host uses NAudio WASAPI (Host/DingAudioPlayer.cs) and is Windows-only in practice.

Clients. Mcp/DingsHostClient.cs, used by the MCP bridge (both stdio and --http) and by the bridge's direct flags --play, --get-volume, --set-volume, --mute (Mcp/Program.cs:9-32). Nothing else in the repo opens the pipe.

Framing (identical in both directions): [int32 length][MessagePack body]. The length is BitConverter.GetBytes(int), so native byte order (little-endian on every platform this builds for, but the code does not fix it). Valid length is 1 to 1,048,576 bytes; outside that the reader throws (DingsPlaybackHost.cs:86-87, DingsHostClient.cs:42). Body is MessagePackSerializer of the keyed records below. One request, one response, then the server disposes the pipe (DingsPlaybackHost.cs:24-36). No streaming, no pipelining, no request id.

Request DingsCommand (DingsProtocol.cs:13-19), keyed:

key	field	note
0	Version	must equal DingsProtocol.Version = 1, else status incompatible (DingsPlaybackHost.cs:41)
1	Kind	Ping, Play, StopAll, GetVolume, SetVolume, SetMuted (:11)
2	EventId	catalog event id, Play only
3	InstrumentId	catalog instrument id, Play only
4	Value	Play: gain 0..1; SetVolume: volume 0..1; SetMuted: >= .5 means muted

Response DingsResponse (DingsProtocol.cs:21-31): Version, Succeeded, Status, Message, PlaybackId, Volume, Muted, HostProcessId, SessionName (default "AquaSynth Dings"). Every response carries current volume and mute, built at DingsPlaybackHost.cs:79-80.

Per kind (DingsPlaybackHost.cs:39-62): Ping and GetVolume are the same branch (status ready). SetVolume rejects non-finite or out-of-range values (rejected) and otherwise sets audio.Volume (volume-set). SetMuted -> muted / unmuted. StopAll -> stopped. Play (:64-77) validates event, instrument and gain, renders each note through the daemon, queues each WAV with its delay, and answers playing with a fresh ding-<guid> PlaybackId. The answer comes after rendering and queueing, not after sound. PlaybackId is not stored and nothing takes it as input. Any exception becomes Succeeded = false, Status = "failed", Message = ex.Message (:32-35), provided the pipe is still connected.

Client behaviour (Mcp/DingsHostClient.cs:15-48): the client validates the response Version (:46). Connect timeout 350 ms; on TimeoutException or IOException it launches the host (StartHost, :50-56: newest AquaSynthDingsHost.exe under tools/AquaSynthDingsHost/bin, hidden window, working directory the repo root found by walking up to AquaSynth.sln) and retries up to 20 times at 500 ms connect with 100 ms gaps, all inside a 15 s overall timeout. A Succeeded = false response is turned into InvalidOperationException(response.Message) by DingService.EnsureSuccess (DingService.cs:22-26).

MCP side, for completeness. Tools (Mcp/DingTools.cs): play_ding, get_agent_instrument, claim_instrument, list_ding_events, list_instruments, stop_dings, get_volume, set_volume, mute_dings. Transports: stdio by default (Program.cs:56-65); --http [url] serves Streamable HTTP at /mcp, default http://127.0.0.1:17878, singleton by mutex Local\GameCult.AquaSynthDings.McpHttp.v1 (Program.cs:34-54). Only play_ding, get_agent_instrument, claim_instrument touch agent identity; the volume and stop tools address the whole host and are machine-global.

Not authenticated beyond the OS. CurrentUserOnly limits it to the same Windows user. Any process of that user can send Play. There is no per-caller identity on the pipe: DingsCommand carries an instrument, not a caller, so the Host cannot know who asked.

PROPOSED: one owner (a recommendation for the stewarding decision, not decided)

Proposal. DingCatalog (src/AquaSynth.Dings) becomes the only place that decides what a voice is, and also the only place that derives the daemon keys from it. Its instrument gains a content revision (a hash of Script plus the parameters that matter), and one function in that assembly produces PatchId, FaustName and the revision for the daemon (AquaLower and the test need only the faust-name part of it, not patchId or revision). Everything else keys on the catalog id and takes the rest from the catalog.

What the others become.

• B (Host/daemon): the Host stops composing patchId/faustName/revision; it calls the catalog function. AquaLower/Program.cs:19 and DingCatalogTests.cs:45 call only the faust-name slice of it. The daemon keeps its session and file naming; those are daemon-internal and derive from what it is given.
• C (registry): stays in the bridge as a cache of choices, but its assignment function moves beside the catalog (so a future export can call it) and its key becomes an agent identity rather than an MCP session id. This depends on the open question below.
• D (dings-voices): stays a separate synthesizer for sender notifications, since its voices are JS functions with no Faust form. Its link to the owner is by reference: the neutral fallback names a catalog instrument id instead of a second warm-bell. Whether sender voices should ever become catalog instruments is a product fork, not part of this change.
• E: Earcon Workshop IDENTITIES either read their shared values from a generated file (as lowered-dings already is) or drop the shared ids; the drifted values in the table above are resolved by whoever owns the workshop's tuning.

Why this owner. A already has the most readers (the list in section A), is the only definition of the script, and is the only one the host cannot run without. C, D and E are all consumers or approximations of it by name.

Migration order (each step independent and reversible):

1. Add the catalog function; switch AquaDaemonClient.cs:20 and AquaLower onto it; delete the test's private copy (see the oracle risk below). Pure refactor while revision stays the literal 1: the compile key, and so the session id, stay equal for unchanged scripts, which is checkable by comparing receipts before and after.
2. Decide the agent-identity question (below); change the registry key. Wire-visible: existing sessions lose their hashed assignment.
3. Content revision: DEFERRED, not scheduled here. Replacing the literal revision = 1 with a catalog hash changes every compile key and session id (and the sessions/<...>.cc file names), so it breaks step 1's equality check by design. It needs its own decision on what feeds the hash and whether old session files are left or removed.
4. Remove the duplicate gates in DingService.cs:9-11 or have the Host's gate be the single one (the bridge then only forwards). Keep whichever side the tests (DingsBridgeTests) need for fail-fast, but one of them must be the owner.
5. Point the neutral fallback and Earcon Workshop at the catalog.

Risks.

• Step 2 changes what agents hear on first use after deploy; nobody has listened to a before/after.
• The deferred content revision changes session ids and session file names, visible in receipts but not read by anything I found.
• Oracle loss in step 1: deleting the test's private "dings_" + id copy makes LoweredDingsFedToTheFeelMeterMatchTheCatalog compare the shared function against itself. The test should keep an independent expected value (a literal per instrument or the checked-in .dsp header) so a wrong rule still fails.
• Collapsing 8 senders onto 4 instruments would lose distinctness; the proposal does not do that, and I am recommending against it without having listened to either set.
• Moving derivation to the catalog assembly makes AquaSynth.Dings the home of daemon-protocol knowledge; if the daemon is expected to run without that assembly, this is the wrong direction. I did not check whether anything else wants that.

Confidence. Moderate on the owner choice; it follows reader counts and the write path, not any prior art on identity registries. Lower on step 2, because it depends on what the MCP bridge can learn about its caller.

Could not verify

• That "four owners" in the follow-up means these four. The count here is mine.
• Whether an MCP client can tell the bridge which agent it is. The only identity read in source is server.SessionId (DingTools.cs:45); I did not inspect the MCP SDK for client-info fields, or any harness config.
• What Ratatoskr's dings.ts actually reads and whether it shares any naming with DingCatalog; it is not in this repo.
• Behaviour at runtime: reconnect session ids, store growth under .aquasynth/dings-host, and whether the Host's Ping/GetVolume have different callers in practice. The pipe protocol above is from reading, not from a captured exchange. Nothing was built, run, or listened to for this note.