Merge pull request #10 from sonicfieldlabs/agent/germ-v0.4.1

Release GERM 0.4.1

Author: emeisazam

.github/workflows/ci.yml

@@ -7,17 +7,24 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
       - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
-          node-version: "22"
+          node-version: "22.22.3"
       - name: Install Python dependencies
-        run: uv sync --extra dev
+        run: uv sync --extra dev --locked
       - name: Python tests
         run: uv run pytest -q
       - name: Ruff
@@ -38,7 +45,10 @@ jobs:
       - name: Dashboard syntax
         run: |
           node --check dashboard/static/app.js
+          node --check dashboard/static/audio_engine.js
+          node --check dashboard/static/cosmoaudition.js
           node --check dashboard/static/dish.js
+          node --check dashboard/static/docs_theme.js
           node --check dashboard/static/micro_forms.js
           node --check dashboard/static/micro_render.js
           node --check dashboard/static/micro_unicode.js

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.4.1 — Sonic Matter Framework contract corrections
+
+- Fixed the Cosmoaudition frame bridge to consume the published
+  `outputValue` field, expose an explicit GERM `value`, and retain the control's
+  status, mapping parameters, confidence, and epistemic note. Real applied,
+  held, and uncertainty routes are no longer silently withheld.
+- Kept canonical `sound_id`, Sonic Lineage, and Earworm identifiers stable
+  when filenames change; refreshed written MASA sidecars after path changes and
+  refused renames that would break an immutable Akousmata file locator. Rename
+  companion writes are transactional, and matching deferred-latent locators
+  follow their audio without changing identity.
+- Restricted bulk file deletion's primary path to supported audio formats,
+  required the actual metadata companion, preserved Akousmata locators, and
+  removed only verified written MASA sidecars under explicit companion-delete
+  semantics.
+- Preserved Cosmoaudition frame-level signals and sources beside resolved
+  routes, and withheld malformed or out-of-range executable controls with an
+  explicit bridge reason.
+- Accepted finite JavaScript wire numbers whose integer spelling exceeds a
+  signed 64-bit persistence value, so high-magnitude observations such as the
+  Bitcoin hashrate cannot invalidate an otherwise valid modulation frame.
+- Aligned active project language to **Sonic Matter Framework**: MASA
+  describes, Cosmoaudition observes and modulates, and GERM cultivates. The
+  projects remain distinct.
+
 ## 0.4.0 — Sonic Matter Stack alignment
 
 - **Fixed a MASA protocol break.** Every sidecar cited

CITATION.cff

@@ -5,8 +5,8 @@ authors:
   - family-names: "Isaza"
     given-names: "eme"
     affiliation: "Sonic Field Labs"
-version: "0.4.0"
-date-released: "2026-08-07"
+version: "0.4.1"
+date-released: "2026-08-09"
 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."

README.md

@@ -8,11 +8,11 @@ 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.4.0`.
+Current release: `0.4.1`.
 
 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
+through the [Sonic Matter Framework](#sonic-matter-framework-integration), whose
 protocol boundary is MASA 0.1.0.
 
 GERM is an independent Sonic Field Labs project. It can use Stable Audio 3
@@ -127,20 +127,21 @@ promising one universal hardware minimum.
 All three scales use the same module graph, semantic FX bridge, sessions,
 library, and lineage model.
 
-## Sonic Matter Stack integration
+## Sonic Matter Framework integration
 
 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:
+heard, remembered, and re-listened; the **Sonic Matter Framework** joins three
+distinct projects around sound described *as matter*: MASA supplies the
+descriptive protocol, Cosmoaudition supplies attributed observations and
+modulation decisions, and GERM cultivates sound while retaining provenance and
+lineage. GERM keeps those roles distinct while making their contracts usable
+inside its cultivation graph:
 
 | 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. |
+| GERM Matter Analysis | — | A bounded local analyzer informed by the shared measured / inferred / unavailable distinction; it is not a claim of listening or a fourth framework project. |
 | [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
@@ -173,9 +174,13 @@ 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.
+Out-of-range or structurally invalid controls are withheld with an explicit
+bridge reason. Frame-level `signals` and `sources` travel beside the routes so
+their source, unit, sphere, epistemic status, and temporal character remain
+traceable through `signalId`. 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
 

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.4.0"
-BUNDLE_VERSION="6"
+MARKETING_VERSION="0.4.1"
+BUNDLE_VERSION="7"
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 # Keep the runnable bundle where repository users expect to find apps. The

dashboard/static/app.js

@@ -3487,7 +3487,7 @@ async function renameFile(audioPath, metadataPath, newStem) {
 async function deleteSelectedFiles() {
   const items = [...rackSelectedKeys].map(rackItemByKey).filter(Boolean);
   if (!items.length) return;
-  if (!confirm(`Permanently delete ${items.length} selected sound file(s) from disk? This cannot be undone.`)) return;
+  if (!confirm(`Permanently delete ${items.length} selected sound(s) and their linked local metadata/MASA companions from disk? Akousmata-linked sounds are preserved. This cannot be undone.`)) return;
 
   beginWork("Deleting Files", `${items.length} items`);
   try {
@@ -3514,7 +3514,7 @@ async function deleteSelectedFiles() {
 
 async function deleteSingleFile(audioPath, metadataPath) {
   const filename = audioPath.split("/").pop();
-  if (!confirm(`Permanently delete "${filename}" from disk? This cannot be undone.`)) return;
+  if (!confirm(`Permanently delete "${filename}" and its linked local metadata/MASA companions from disk? Akousmata-linked sounds are preserved. This cannot be undone.`)) return;
 
   beginWork("Deleting File", filename);
   try {

docs/api_reference.md

@@ -864,8 +864,15 @@ The server only reveals files inside the configured output directory.
 }
 ```
 
-Renames the audio file (and metadata file, when given) to a sanitized stem and rewrites
-the path/id fields inside the metadata JSON, rolling back on failure.
+Renames the audio file (and its actual metadata companion, when one exists) to a sanitized stem and
+rewrites storage paths inside the metadata JSON. Canonical `sound_id`, lineage,
+and Earworm identifiers remain stable. Same-name metadata is discovered even
+when the caller omits it, and only a metadata object that actually identifies
+the audio can be used. Matching deferred-latent locators are rewritten. A
+verified written MASA sidecar is refreshed transactionally in place; a failed
+companion write rolls the rename back. Sounds remembered in Akousmata, or with
+an unresolved requested memory write, are refused because moving their audio
+could break the shared record's immutable file locator.
 
 ## POST /files/delete
 
@@ -880,4 +887,10 @@ the path/id fields inside the metadata JSON, rolling back on failure.
 }
 ```
 
-Best-effort bulk delete of output files (max 500 items per request).
+Best-effort bulk delete of audio output files and their explicitly supplied,
+verified metadata companions (max 500 items per request). The primary path must
+use a supported audio extension. If companion metadata exists, its exact path
+is required; a verified written MASA sidecar is then deleted with that local
+record. Remembered or unresolved requested Akousmata are refused because their
+shared `file://` locator must remain valid. Unrelated JSON and unresolved
+sidecar evidence are preserved.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "germ"
-version = "0.4.0"
+version = "0.4.1"
 description = "Local-first modular laboratory for generative microsound, Stable Audio workflows, and lineage-aware cultivation."
 readme = "README.md"
 license = "MPL-2.0"

server/cosmoaudition.py

@@ -50,9 +50,33 @@ def _reject_nonfinite_json(value: str) -> None:
     raise ValueError(f"non-finite JSON constant: {value}")
 
 
+def _decode_json_integer(value: str) -> int | float:
+    """Keep ordinary integers exact and accept finite JavaScript wire numbers.
+
+    Cosmoaudition serializes IEEE-754 numbers with ``JSON.stringify``. A value
+    such as the Bitcoin hashrate can therefore arrive with an integer spelling
+    outside GERM's signed-64-bit persistence boundary even though the producer
+    already represents it as a finite float. Preserve normal JSON integers as
+    integers, but materialize those wider wire values as finite floats so one
+    observation cannot invalidate the complete modulation frame.
+    """
+
+    decoded = int(value)
+    if -(2**63) <= decoded < 2**63:
+        return decoded
+    widened = float(value)
+    if not math.isfinite(widened):
+        raise ValueError("JSON integer exceeds the finite-number boundary")
+    return widened
+
+
 def _decode_json_object(raw: bytes) -> dict[str, Any]:
     try:
-        value = json.loads(raw, parse_constant=_reject_nonfinite_json)
+        value = json.loads(
+            raw,
+            parse_constant=_reject_nonfinite_json,
+            parse_int=_decode_json_integer,
+        )
     except (UnicodeError, json.JSONDecodeError, ValueError, RecursionError) as exc:
         raise CosmoauditionBridgeError("Cosmoaudition returned invalid JSON") from exc
     if not isinstance(value, dict):
@@ -187,6 +211,60 @@ def status(self) -> dict[str, Any]:
 #: `skipped` and `refused` carry none; `held` and `uncertainty` carry one that
 #: must keep its status when it travels.
 EXECUTABLE_FRAME_STATUSES = frozenset({"applied", "held", "uncertainty"})
+WITHHELD_FRAME_STATUSES = frozenset({"skipped", "refused"})
+
+
+def _finite_frame_number(value: Any) -> bool:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        return False
+    try:
+        return math.isfinite(value)
+    except OverflowError:
+        # JSON integers are unbounded in Python but not in Cosmoaudition's
+        # JavaScript runtime. They cannot become executable control values.
+        return False
+
+
+def _frame_object_list(
+    frame: dict[str, Any],
+    key: str,
+    *,
+    required: bool = False,
+) -> list[dict[str, Any]]:
+    value = frame.get(key)
+    if value is None:
+        if required:
+            raise CosmoauditionBridgeError(f"Cosmoaudition frame is missing its {key}")
+        return []
+    if not isinstance(value, list) or any(not isinstance(item, dict) for item in value):
+        raise CosmoauditionBridgeError(f"Cosmoaudition frame has invalid {key}")
+    return list(value)
+
+
+def _control_bridge_reason(control: dict[str, Any], status: Any) -> str | None:
+    if status not in EXECUTABLE_FRAME_STATUSES:
+        return None if status in WITHHELD_FRAME_STATUSES else "invalid-status"
+    if any(
+        not isinstance(control.get(key), str) or not control[key].strip()
+        for key in ("mappingId", "signalId", "target")
+    ):
+        return "invalid-route-identity"
+
+    output_value = control.get("outputValue")
+    if not _finite_frame_number(output_value):
+        return "invalid-output-value"
+    output_range = control.get("outputRange")
+    if (
+        not isinstance(output_range, (list, tuple))
+        or len(output_range) != 2
+        or not all(_finite_frame_number(value) for value in output_range)
+        or output_range[0] == output_range[1]
+    ):
+        return "invalid-output-range"
+    lower, upper = sorted(output_range)
+    if not lower <= output_value <= upper:
+        return "output-outside-range"
+    return None
 
 
 def modulation_routes_from_frame(frame: dict[str, Any]) -> dict[str, Any]:
@@ -201,32 +279,51 @@ def modulation_routes_from_frame(frame: dict[str, Any]) -> dict[str, Any]:
     went missing is a fact about the frame.
     """
 
-    controls = frame.get("controls")
-    if not isinstance(controls, list):
-        raise CosmoauditionBridgeError("Cosmoaudition frame is missing its controls")
+    if frame.get("contract") != COSMOAUDITION_MODULATION_CONTRACT:
+        raise CosmoauditionBridgeError(
+            "Cosmoaudition frame does not declare "
+            f"{COSMOAUDITION_MODULATION_CONTRACT}"
+        )
+
+    controls = _frame_object_list(frame, "controls", required=True)
+    signals = _frame_object_list(frame, "signals")
+    sources = _frame_object_list(frame, "sources")
 
     routes: list[dict[str, Any]] = []
     withheld: list[dict[str, Any]] = []
     for control in controls:
-        if not isinstance(control, dict):
-            continue
         status = control.get("status")
+        output_value = control.get("outputValue")
+        bridge_reason = _control_bridge_reason(control, status)
+        executable = status in EXECUTABLE_FRAME_STATUSES and bridge_reason is None
         entry = {
             "target": control.get("target"),
             "mappingId": control.get("mappingId"),
             "signalId": control.get("signalId"),
+            "layer": control.get("layer"),
             "status": status,
             "reason": control.get("reason"),
-            "value": control.get("value"),
-            "unit": control.get("unit"),
-            "attribution": control.get("attribution"),
+            "bridgeReason": bridge_reason,
+            # ``value`` is GERM's consumer-facing route value. Cosmoaudition's
+            # modulation contract names the same field ``outputValue``; keep
+            # both names so the crosswalk is explicit and lossless.
+            "value": output_value if executable else None,
+            "outputValue": output_value if executable else None,
+            "inputValue": control.get("inputValue"),
+            "normalizedInput": control.get("normalizedInput"),
+            "rawNormalizedInput": control.get("rawNormalizedInput"),
+            "mappingAmount": control.get("mappingAmount"),
+            "outputRange": control.get("outputRange"),
+            "curve": control.get("curve"),
+            "smoothingMs": control.get("smoothingMs"),
+            "missingData": control.get("missingData"),
+            "confidence": control.get("confidence"),
+            "epistemicNote": control.get("epistemicNote"),
         }
-        if status in EXECUTABLE_FRAME_STATUSES and isinstance(
-            control.get("value"), (int, float)
-        ) and not isinstance(control.get("value"), bool):
+        if executable:
             routes.append(entry)
         else:
-            withheld.append({**entry, "value": None})
+            withheld.append(entry)
 
     absences = frame.get("absences")
     return {
@@ -237,6 +334,11 @@ def modulation_routes_from_frame(frame: dict[str, Any]) -> dict[str, Any]:
         "originMode": frame.get("originMode"),
         "routes": routes,
         "withheld": withheld,
+        # Preserve frame-level source evidence. `signalId` is the join key; the
+        # input observation's unit/status must not be mistaken for the routed
+        # output parameter's unit/status by flattening the two objects together.
+        "signals": signals,
+        "sources": sources,
         "absences": absences if isinstance(absences, list) else [],
         "attribution": frame.get("attribution") if isinstance(frame.get("attribution"), list) else [],
         "masaRecordHref": frame.get("masaRecordHref"),

server/identity.py

@@ -3,7 +3,7 @@
 
 PRODUCT_NAME = "germ"
 PRODUCT_DESCRIPTION = "open-source modular lab for generative microsound"
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 LEGACY_ENGINE_NAME = "Germinator"
 SOUND_MATTER_CONCEPT = "sound_matter"
 SOUND_MATTER_SCALES = ["micro", "meso", "macro"]