Merge pull request #9 from sonicfieldlabs/agent/sonic-matter-stack-v0.4.0

Release GERM 0.4.0 with the Sonic Matter Stack alignment

Author: emeisazam

.env.example

@@ -62,7 +62,7 @@ GERM_OIDA_TIMEOUT_SECONDS=1800
 
 # Optional local Cosmoaudition System bridge. Germ accepts only an HTTP
 # loopback URL and never contacts astronomical, geological, weather, or other
-# observatory providers itself.
+# observation providers itself.
 GERM_COSMOAUDITION_URL=http://127.0.0.1:8797
 GERM_COSMOAUDITION_TIMEOUT_SECONDS=20
 GERM_COSMOAUDITION_MAX_RESPONSE_BYTES=2097152

.gitignore

@@ -24,6 +24,11 @@ apps/macos/dist/
 apps/germ.app/
 .codex/
 
+# Local tool caches and state
+.uv-cache/
+.uv-tools/
+.playwright-cli/
+
 /*.png
 /*.jpg
 /*.jpeg

CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.4.0 — Sonic Matter Stack alignment
+
+- **Fixed a MASA protocol break.** Every sidecar cited
+  `smo.sonicfield.org`, a pre-release identifier root. `$schema` is a protocol
+  constant rather than a hint, so the published MASA 0.1.0 validator rejected
+  every record GERM had ever written. Records now cite
+  `masa.sonicfield.org` and validate against the released reference
+  implementation.
+- **Fixed a silent modulation bug.** A zero mapping amount was scaled through
+  instead of read as the operator turning a route off. On a reversed output
+  range such as `(760, 180)` that emits `outputRange[0]` — the strongest value
+  the mapping can produce — reported as `applied`. Silence requested, maximum
+  delivered. A zero amount is now `skipped` / `route-disabled`, matching
+  Cosmoaudition's own engine.
+- Added the MASA processing layer to the Micro modules. Each declares a
+  granular or spectral operation in MASA's engine-neutral terms and can emit a
+  portable `masa-processing-request` via `POST /micro/processing-request`;
+  `GET /micro/processing-operations` reports the mapping. GERM states the
+  intention and binds no DSP library.
+- Added the Cosmoaudition modulation framework. The bridge allowlist now covers
+  `/api/modulation`, `/api/frame`, and `/api/snapshot/masa`, and
+  `GET /cosmoaudition/frame` resolves one verified `cosmo/modulation/v0.1`
+  frame into GERM routes. It reads the frame's `controls`, never the bare
+  `values` map, so a value never travels without the decision that produced it;
+  withheld routes and emitted absences are reported rather than dropped.
+  `/api/stream` stays unbridged because Server-Sent Events cannot be read by a
+  bounded request/response client.
+- Added `uncertaintyOutput` to Cosmoaudition mappings, so a `map-uncertainty`
+  policy emits its declared value under an `uncertainty` status instead of
+  degrading silently to `skip`. Declaring the policy without the value is now
+  refused at the schema boundary.
+- Named GERM's place in the **Sonic Matter Stack** alongside the Listening
+  Stack, and retired the earlier "Observatory" naming across the server,
+  dashboard, documentation, and module labels.
+
 ## 0.3.3 — Additive cultivation lineage
 
 - Raised the Earworm/Akousma floor to 0.6.1 so remembered generations cannot

CITATION.cff

@@ -5,8 +5,8 @@ authors:
   - family-names: "Isaza"
     given-names: "eme"
     affiliation: "Sonic Field Labs"
-version: "0.3.3"
-date-released: "2026-08-03"
+version: "0.4.0"
+date-released: "2026-08-07"
 license: "MPL-2.0"
 repository-code: "https://github.com/sonicfieldlabs/germ"
 abstract: "germ is a local generative microsound environment whose generated sounds retain prompts, parents, mutations, listening metadata, and Earworm-compatible lineage."

CONTRIBUTING.md

@@ -23,6 +23,11 @@ provider accountability, safety, accessibility, or reproducibility.
 Do not commit model weights, generated audio, uploads, credentials, `.env`
 files, local paths, private prompts, personal sessions, or provider responses.
 
+Commit messages describe the change and its reason in plain prose. Never add
+`Co-Authored-By` lines or any AI attribution trailer: no assistant, tool, or
+model is listed as an author, co-author, or contributor. Commits carry the
+human author's identity only.
+
 ## Contracts to Preserve
 
 - Cloud egress remains explicit, opt-in, and documented.

README.md

@@ -8,7 +8,12 @@ listened to, and traced through lineage. A listening from Oída can become a
 prompt or source in GERM; a successful render can become a descendant in
 Akousmata and return to Oída for another listening.
 
-Current release: `0.3.3`.
+Current release: `0.4.0`.
+
+GERM is part of two Sonic Field Labs constellations: it cultivates within
+[The Listening Stack](https://sonicfield.org/stack) and describes its material
+through the [Sonic Matter Stack](#sonic-matter-stack-integration), whose
+protocol boundary is MASA 0.1.0.
 
 GERM is an independent Sonic Field Labs project. It can use Stable Audio 3
 providers, but it is not an official Stability AI product.
@@ -122,22 +127,56 @@ promising one universal hardware minimum.
 All three scales use the same module graph, semantic FX bridge, sessions,
 library, and lineage model.
 
-## Sonic Matter Observatory integration
+## Sonic Matter Stack integration
 
-GERM keeps the Observatory components distinct while making their contracts
-usable inside the cultivation graph:
+GERM belongs to two constellations. The Listening Stack is how a sound is
+heard, remembered, and re-listened; the **Sonic Matter Stack** is how sound is
+described *as matter* — its provenance, its measurements, its granular and
+spectral operations, and the observations that modulate it. GERM keeps those
+components distinct while making their contracts usable inside the cultivation
+graph:
 
-| Component | Boundary in GERM |
-| --- | --- |
-| MASA 0.1 | Optional descriptive JSON sidecars under `output/masa/`; never replaces Sonic Lineage or changes a successful render into a failure. |
-| MATERIA | Matter Analysis provides a bounded local analyzer informed by the shared measured / inferred / unavailable distinction; it is not a claim of listening. |
-| Cosmoaudition System | A loopback-only, response-bounded HTTP bridge reads snapshots and source status. GERM never contacts observatory providers directly. |
+| Component | Version / contract | Boundary in GERM |
+| --- | --- | --- |
+| [MASA](https://github.com/sonicfieldlabs/MASA) | 0.1.0 (MIT) | Optional descriptive JSON sidecars under `output/masa/`, citing the published canonical schema at `masa.sonicfield.org`. They never replace Sonic Lineage or turn a successful render into a failure. |
+| MASA Processing | `masa-processing-request` 0.1.0 | Every Micro module declares a granular or spectral operation in MASA's engine-neutral terms. GERM states the intention and binds no DSP library. |
+| MATERIA | — | Matter Analysis provides a bounded local analyzer informed by the shared measured / inferred / unavailable distinction; it is not a claim of listening. |
+| [Cosmoaudition](https://github.com/sonicfieldlabs/cosmoaudition) | `cosmo/modulation/v0.1` | A loopback-only, response-bounded HTTP bridge reads source status, snapshots, and modulation frames. GERM never contacts observation providers directly. |
+
+### Micro modules as MASA processing operations
+
+MASA 0.1.0 carries Roads's granular vocabulary as a protocol layer, so a Micro
+module can say what it wants done to matter without naming an engine:
+
+| Micro module | Operation | Character |
+| --- | --- | --- |
+| Grain Culture | `matter.granulate` | Quasi-synchronous emission at the perceptible grain. |
+| Particle Engine | `matter.granulate` | Dense asynchronous emission, expodec envelopes. |
+| Quanta | `matter.granulate` | The millisecond threshold where a grain stops being a small note and becomes a particle. |
+| Cell Splitter / Colony | `matter.fragment` | Transient-led and grain-led division. |
+| Spectral Tissue / Membrane | `matter.extract` | Spectral strata and bands. |
+| Microscope | `matter.reduce` | Spectral peaks retained for inspection. |
+| Metabolism | `matter.timestretch` | Duration change with declared transient handling. |
+| Swarm | `matter.pitchshift` | Transposition with declared formant handling. |
+
+`GET /micro/processing-operations` reports the mapping; `POST
+/micro/processing-request` builds a portable request. A request is an
+intention, not a receipt: it asserts nothing about what was rendered or heard.
+
+### Modulation
 
 Cosmoaudition mappings are operator-authored control relations. They do not
 claim that a dataset is the literal voice or identity of a source. Missing or
 unfetched observations do not silently become zero or a neutral modulation;
 the route remains inactive until its state is explicit.
 
+`GET /cosmoaudition/frame` reads one modulation frame and resolves it into
+GERM routes. It reads the frame's `controls`, never its bare `values` map:
+a value arrives with the decision that produced it, or it does not arrive.
+Withheld routes and emitted absences are reported rather than dropped. Server-
+Sent Events are deliberately not bridged, because this bridge is a bounded
+request/response client; poll `/cosmoaudition/frame` instead.
+
 ## Listening Stack integration
 
 **Oída hears. GERM cultivates. Akousmata remembers. AKOÚŌ structures. Earworm

apps/macos/script/build_and_run.sh

@@ -6,8 +6,8 @@ APP_NAME="germ"
 EXECUTABLE_NAME="germ-macos"
 BUNDLE_ID="org.sonicfield.germ"
 MIN_SYSTEM_VERSION="13.0"
-MARKETING_VERSION="0.3.3"
-BUNDLE_VERSION="5"
+MARKETING_VERSION="0.4.0"
+BUNDLE_VERSION="6"
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 # Keep the runnable bundle where repository users expect to find apps. The

dashboard/static/app.js

@@ -776,7 +776,7 @@ const FX_MODULES = {
   microscope: { label: "Microscope", description: "Inspect transients, partials, density, and grain behavior" },
   matter_analysis: { label: "Matter Analysis", description: "Measure spectral, temporal, spatial, and inferred material qualities without altering audio" },
   incubator: { label: "Incubator", description: "Slowly evolve a sound population over time" },
-  cosmo_matter_modulator: { label: "Matter Modulator", description: "Route observatory control into granular, spectral, and temporal sound-matter processing" },
+  cosmo_matter_modulator: { label: "Matter Modulator", description: "Route observation control into granular, spectral, and temporal sound-matter processing" },
   loop_doctor: { label: "Loop Doctor", description: "Loop detection, seam repair, and cyclic export" },
   space: { label: "Space", description: "Simple reverb modes" },
   echo: { label: "Echo", description: "Delay modes and feedback" },
@@ -1005,7 +1005,7 @@ const FX_SEMANTIC_PROFILES = {
   },
   cosmo_matter_modulator: {
     family: "cosmoaudition",
-    prompt: ({ params }) => `observatory-shaped sound matter, ${Number(params.density ?? 0.5) > 0.6 ? "dense" : "open"} material pulses, bounded planetary modulation`,
+    prompt: ({ params }) => `observation-shaped sound matter, ${Number(params.density ?? 0.5) > 0.6 ? "dense" : "open"} material pulses, bounded planetary modulation`,
     negative: () => "literal one-to-one data sonification, source identity claim",
     generation: ({ params, amount }) => ({
       inpaintDensity: Number(params.density ?? 0.5) * 0.18 * amount,
@@ -3774,7 +3774,7 @@ function modulatorLabel(modulatorType) {
     audio_to_control: "Audio-to-Control",
     gesture_recorder: "Gesture Recorder",
     macro_modulator: "Macro",
-    cosmo_observation: "Observatory Source",
+    cosmo_observation: "Observation Source",
     cosmo_cosmic_field: "Cosmic Field",
     cosmo_earth_field: "Earth Field",
     cosmo_biosphere_field: "Biosphere Field",
@@ -4419,7 +4419,7 @@ async function refreshCosmoauditionNode(nodeId, { archive = false } = {}) {
   const index = canvasNodes.findIndex((item) => item.id === nodeId);
   const node = normalizeModulatorNode(canvasNodes[index]);
   if (!node || !COSMOAUDITION_MODULATOR_TYPES.has(node.modulatorType)) return;
-  beginWork(archive ? "Archiving Observation" : "Reading Observatory", node.label);
+  beginWork(archive ? "Archiving Observation" : "Reading Observation", node.label);
   try {
     let payload;
     let archiveId = node.config?.archiveId || "";
@@ -4516,7 +4516,7 @@ async function refreshCosmoauditionNode(nodeId, { archive = false } = {}) {
     canvasNodes[index] = node;
     canvasSaveState();
     renderCanvas();
-    finishWork("Observatory Unavailable", "bad", node.config.status);
+    finishWork("Observation Unavailable", "bad", node.config.status);
   }
 }
 
@@ -9905,7 +9905,7 @@ function canvasModulatorNodeMarkup(node, selected, style) {
     audio_to_control: "Audio features become generation controls.",
     gesture_recorder: "Recorded movement for generation values.",
     macro_modulator: "Manual control source.",
-    cosmo_observation: "Project-neutral local observatory signal source.",
+    cosmo_observation: "Project-neutral local observation signal source.",
     cosmo_cosmic_field: "Cosmic observations as bounded control material.",
     cosmo_earth_field: "Atmospheric and geological observations as bounded control material.",
     cosmo_biosphere_field: "Species and biosphere observations as bounded control material.",

dashboard/static/index.html

@@ -733,9 +733,9 @@ <h3>Microsound Modules</h3>
                         </section>
                         <section class="canvas-source-panel cosmoaudition-source-panel" data-source-panel="cosmoaudition" aria-label="Cosmoaudition modules" hidden>
                           <p class="canvas-source-panel-note">Observations become attributed, bounded control material through authored mappings—not claims that data is a source's literal voice.</p>
-                          <button class="source-tool-card" type="button" title="Observatory Source" aria-label="Add Observatory Source" data-action="canvas-source-option" data-source="modulator" data-modulator="cosmo_observation">
+                          <button class="source-tool-card" type="button" title="Observation Source" aria-label="Add Observation Source" data-action="canvas-source-option" data-source="modulator" data-modulator="cosmo_observation">
                             <span class="source-tool-icon"><svg class="source-tool-svg" viewBox="0 0 24 24" aria-hidden="true"><use href="#sourceIconEcology"></use></svg></span>
-                            <strong class="source-tool-title">Observatory Source</strong>
+                            <strong class="source-tool-title">Observation Source</strong>
                             <span class="source-tool-desc">Read a bounded local observation snapshot.</span>
                           </button>
                           <button class="source-tool-card" type="button" title="Cosmic Field" aria-label="Add Cosmic Field" data-action="canvas-source-option" data-source="modulator" data-modulator="cosmo_cosmic_field">

docs/germ_micro_architecture.md

@@ -70,7 +70,7 @@ categories:
 
 | Module | Role |
 | --- | --- |
-| Observatory Source | Reads one bounded local snapshot. |
+| Observation Source | Reads one bounded local snapshot. |
 | Cosmic Field | Selects `cosmos` observations. |
 | Earth Field | Selects atmospheric and geological observations. |
 | Biosphere Field | Selects biosphere observations. |
@@ -81,11 +81,22 @@ categories:
 | Semantic Field | Relates a normalized value to attributed descriptive context. |
 | Uncertainty Field | Makes confidence, staleness, and source error available as control. |
 | Observation Archive | Replays a bounded local observation with provenance. |
-| Matter Modulator | Applies observatory-routed control to granular and spectral matter parameters. |
+| Matter Modulator | Applies observation-routed control to granular and spectral matter parameters. |
 
 GERM connects only to the separate Cosmoaudition System on an explicit HTTP
 loopback URL. It accepts no redirects, proxies only allowlisted routes, ignores
-environment proxies, and caps the response body. Provider credentials and
+environment proxies, and caps the response body. The allowlist covers
+`/health`, `/api/sources`, `/api/snapshot`, `/api/snapshot/masa`,
+`/api/modulation`, and `/api/frame`. `/api/stream` is deliberately excluded:
+it is Server-Sent Events, and this bridge is a bounded request/response client
+that reads a complete body and closes.
+
+A modulation frame is verified against the contract it claims —
+`cosmo/modulation/v0.1` — before it is read. `GET /cosmoaudition/frame`
+resolves one frame into GERM routes using its `controls`, never the bare
+`values` map that exists for transports carrying only numbers. Using that map
+would turn a skipped route into a real zero. Withheld routes and emitted
+absences travel in the response instead of disappearing from it. Provider credentials and
 astronomical, geological, weather, biosphere, human, or machine APIs remain on
 the Cosmoaudition side of the boundary.
 
@@ -95,6 +106,38 @@ clocked routes. Mapping receipts retain signal, source, confidence,
 epistemic status, temporal character, mapping status, and the statement that
 the relation is authored rather than a source-identity claim.
 
+## MASA processing layer
+
+MASA 0.1.0 carries the granular and spectral vocabulary as a protocol layer, so
+a Micro module can state what it wants done to matter without naming a DSP
+engine. Each module declares one operation:
+
+| Module | MASA operation |
+| --- | --- |
+| Grain Culture, Particle Engine, Quanta | `matter.granulate` |
+| Cell Splitter, Colony | `matter.fragment` |
+| Spectral Tissue, Membrane | `matter.extract` |
+| Microscope | `matter.reduce` |
+| Metabolism | `matter.timestretch` |
+| Swarm | `matter.pitchshift` |
+
+The parameters are the module's own character rather than one shared default.
+Quanta works between one and ten milliseconds, where a grain stops being a
+small note and becomes a particle and the envelope dominates what is heard;
+Grain Culture cultivates at the perceptible grain with quasi-synchronous
+emission; Particle Engine is dense asynchronous emission. Spectral Tissue reads
+strata rather than a single band.
+
+`GET /micro/processing-operations` reports the mapping. `POST
+/micro/processing-request` builds a portable `masa-processing-request`, merging
+operation floor, module character, and authored parameters in that order so a
+partial override cannot drop a sibling the contract still requires.
+
+A processing request is an intention, not a receipt. It carries no `$schema`
+member, because the request schema declares none and forbids what it does not
+declare. It asserts nothing about what was rendered, and nothing about what was
+heard — audition remains outside this boundary.
+
 ## Persisted Control Contracts
 
 Two backend contracts now make the conceptual layer reusable outside the dashboard: