From c98a12baf40a18dcd667a7ad34da4b9fb4613c9c Mon Sep 17 00:00:00 2001
From: Vuong Hoang <vh@phasefinal.com>
Date: Mon, 1 Jun 2026 18:05:56 -0700
Subject: [PATCH] catalog(fish-s2): opt references into togglable;
 catalog_version 1->2
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

asset-engine shipped the per-field enable-toggle (v0.1.14/.15) — the
durable fix for the "form submits untouched fields" family. A field
marked togglable:true renders with an OFF-by-default switch: while off
the control is disabled (excluded from submission) AND the server skips
injecting its default, so it is genuinely not sent until the user opts
in.

Per operator direction, opt fish-s2's `references` (inline-base64
Custom-clone) field in — it already satisfies the togglable-requires-
optional validator (optional:true, no default). The advanced clone
field now renders dormant and can never silently override the Voice
dropdown again.

This is a SCHEMA change (new CatalogField property), so:
- services.schema.json: add `togglable` (boolean, default false),
  mirroring the asset_engine Pydantic model that generates this schema.
- catalog_version 1 -> 2 (header: bump on schema changes).
- CATALOG-CONTRACT.md: consumer pin note -> catalog_version=2.

Scoped to `references` only. The chatterbox/dia2 clone fields are the
same family but NOT toggled: dia2 deliberately defaults voice_mode=clone
+ a clone ref as its stable out-of-box voice, and toggling that field
would change dia2's default-voice behavior (the earlier 404 fix).

Validated: jsonschema accepts togglable; additionalProperties:false
guard still rejects unknown props.
---
 docs/asset-engine/CATALOG-CONTRACT.md  | 2 +-
 docs/asset-engine/services.schema.json | 6 ++++++
 docs/asset-engine/services.yaml        | 3 ++-
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/asset-engine/CATALOG-CONTRACT.md b/docs/asset-engine/CATALOG-CONTRACT.md
index ca31fb5..52d74a5 100644
--- a/docs/asset-engine/CATALOG-CONTRACT.md
+++ b/docs/asset-engine/CATALOG-CONTRACT.md
@@ -144,7 +144,7 @@ reference implementation of this pattern; copy the script shape from
 
 | Consumer                                    | Vendored at                          | Pin policy        |
 |---------------------------------------------|--------------------------------------|-------------------|
-| `asset_engine` (FastAPI/HTMX UI; ~/development/asset_engine/) | `data/services.yaml` + `data/services.yaml.lock` | catalog_version=1 |
+| `asset_engine` (FastAPI/HTMX UI; ~/development/asset_engine/) | `data/services.yaml` + `data/services.yaml.lock` | catalog_version=2 |
 
 When you add a consumer, add a row here in the same PR that lands
 the consumer. This list is what we audit when planning a
diff --git a/docs/asset-engine/services.schema.json b/docs/asset-engine/services.schema.json
index ff63527..5949afe 100644
--- a/docs/asset-engine/services.schema.json
+++ b/docs/asset-engine/services.schema.json
@@ -85,6 +85,12 @@
           "title": "Optional",
           "type": "boolean"
         },
+        "togglable": {
+          "default": false,
+          "description": "When true, the consumer renders this field with an OFF-by-default enable switch; while off the control is disabled (excluded from submission) AND the field's default is NOT injected, so it is genuinely not sent until the user opts in. Requires optional=true. Used to keep advanced override fields (e.g. inline clone references) from silently overriding primary controls.",
+          "title": "Togglable",
+          "type": "boolean"
+        },
         "default": {
           "default": null,
           "title": "Default"
diff --git a/docs/asset-engine/services.yaml b/docs/asset-engine/services.yaml
index c4e7459..ed4d811 100644
--- a/docs/asset-engine/services.yaml
+++ b/docs/asset-engine/services.yaml
@@ -16,7 +16,7 @@
 # specific service's parameter shape changes. Both let downstream
 # consumers detect drift.
 
-catalog_version: 1
+catalog_version: 2
 
 services:
   - id: kokoro
@@ -763,6 +763,7 @@ services:
         label: Custom clone (inline base64)
         section: advanced
         optional: true
+        togglable: true
         description: >
           Power-use: zero-shot clone from a reference NOT in the staged library
           — array of {audio: <base64-encoded WAV bytes>, text: "transcript"}.