From df8769995a6b0614ab655632ac6fe055227fc7f1 Mon Sep 17 00:00:00 2001 From: Jeffrey Louden Date: Sun, 12 Jul 2026 22:23:54 -0400 Subject: [PATCH] fix(io): review follow-ups and usb-b-mini vocabulary expansion Apply verified CodeRabbit findings from #539: Bastl Klik clock output uses type clock; Mackie DLM12 channel 1 is mic and channel 2 is instrument (per owner's manual); io-types clock comment drops the connector reference; docs no longer suggest trs as a connection value; CONTEXT.md and CLAUDE.md reflect that io type is enforced via E117. Expand the connection vocabulary with usb-b-mini (verified against the Bastl Klik manual), canonicalize mini-usb on the Artiphon INSTRUMENT 1, and canonicalize trs/minijack on the Xone:43 to 1/4-inch and 1/8-inch. Encode the expansion policy in CLAUDE.md: verified new values grow the schema instead of being force-fit onto near-miss values. Co-Authored-By: Claude Fable 5 --- .changeset/spicy-jars-clap.md | 5 +++++ CLAUDE.md | 20 +++++++++++++------- data/hardware/allen-and-heath-xone43.yaml | 12 ++++++------ data/hardware/artiphon-instrument-1.yaml | 2 +- data/hardware/bastl-instruments-klik.yaml | 2 +- data/hardware/mackie-dlm12.yaml | 4 ++-- docs/VALIDATION_ERRORS.md | 3 ++- schema/CONTEXT.md | 1 + schema/io-connections.yaml | 1 + schema/io-types.yaml | 2 +- 10 files changed, 33 insertions(+), 19 deletions(-) create mode 100644 .changeset/spicy-jars-clap.md diff --git a/.changeset/spicy-jars-clap.md b/.changeset/spicy-jars-clap.md new file mode 100644 index 000000000..8d8e29b1d --- /dev/null +++ b/.changeset/spicy-jars-clap.md @@ -0,0 +1,5 @@ +--- +"catalog": patch +--- + +IO vocabulary follow-ups from the #539 review: correct Bastl Klik clock output to `type: clock`, correct Mackie DLM12 channel inputs to `mic`/`instrument`, add `usb-b-mini` to the connection vocabulary (Bastl Klik, Artiphon INSTRUMENT 1), canonicalize Xone:43 connections (`trs` → `1/4-inch`, `minijack` → `1/8-inch`), and update CLAUDE.md/CONTEXT.md/VALIDATION_ERRORS.md to reflect enforced IO types (E117) and the expand-the-vocabulary policy. diff --git a/CLAUDE.md b/CLAUDE.md index 3003389c2..73d920c9a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,8 +48,8 @@ Note: Slugs are derived from filenames, not stored in the YAML files. **`manufacturer`** must be a slug reference (the manufacturer's filename without `.yaml`), not the display name: ```yaml -manufacturer: hologram-electronics # correct (slug) -manufacturer: Hologram Electronics # wrong (display name) +manufacturer: hologram-electronics # correct (slug) +manufacturer: Hologram Electronics # wrong (display name) ``` **`description`** uses flow scalar format (Prettier auto-wraps long lines): @@ -95,16 +95,22 @@ io: **IO field validation** uses a two-tier system: -- **Strict (errors, blocks CI):** `signalFlow`, `category`, `position`, `price.currency` +- **Strict (errors, blocks CI):** `signalFlow`, `category`, `type`, `position`, `price.currency` - `signalFlow`: input, output, bidirectional - `category`: audio, midi, digital, power + - `type`: closed vocabulary in `schema/io-types.yaml` — unknown values fail with E117 - `position`: Top, Bottom, Left, Right - `currency`: ISO 4217 codes (USD, EUR, GBP, etc.) — see `schema/currencies.yaml` -- **Advisory (warnings, non-blocking):** `type`, `connection`, `link.type` - - Known values listed in `schema/io-types.yaml`, `schema/io-connections.yaml`, `schema/link-types.yaml` +- **Advisory (warnings, non-blocking):** `connection`, `link.type` + - Known values listed in `schema/io-connections.yaml`, `schema/link-types.yaml` - Unknown values produce warnings in `pnpm validate` output - Add new values to schema files via PR when they're confirmed valid +**The vocabularies are meant to grow.** Enforcement catches mistakes (connectors +in `type`, vague values); it must not force-fit genuinely new signals or +connectors onto near-miss values. When an import surfaces a legitimate new value +(verify via manual/photos), add it to the schema vocabulary in the same PR. + **Semantic distinction:** `type` describes the signal characteristic (line, instrument, headphone, midi, usb, expression). `connection` describes the physical connector (1/4-inch, xlr, usb-c, 5-pin din). Don't swap them. **Passive speakers use `speaker-level`, not `line`.** Passive-loudspeaker inputs @@ -171,7 +177,7 @@ Use `supersedes` to link product generations, form factor variants, and major ve # pro-c-3.yaml name: Pro-C 3 manufacturer: fabfilter -supersedes: 7QMeWge0fOrmQz_oVLCKk # ID of Pro-C 2 +supersedes: 7QMeWge0fOrmQz_oVLCKk # ID of Pro-C 2 identifiers: au: com.fabfilter.Pro-C.AU.3 ``` @@ -182,7 +188,7 @@ To find the ID of a product you want to reference, open its YAML file and look f ```yaml # Example from pro-c-2.yaml -id: 7QMeWge0fOrmQz_oVLCKk # ← Use this value for supersedes +id: 7QMeWge0fOrmQz_oVLCKk # ← Use this value for supersedes name: Pro-C 2 manufacturer: fabfilter ``` diff --git a/data/hardware/allen-and-heath-xone43.yaml b/data/hardware/allen-and-heath-xone43.yaml index 4f7e15e81..205e774c8 100644 --- a/data/hardware/allen-and-heath-xone43.yaml +++ b/data/hardware/allen-and-heath-xone43.yaml @@ -109,42 +109,42 @@ io: signalFlow: output category: audio type: line - connection: trs + connection: 1/4-inch maxConnections: 1 position: Left - name: X:FX Send R signalFlow: output category: audio type: line - connection: trs + connection: 1/4-inch maxConnections: 1 position: Left - name: X:FX Return L signalFlow: input category: audio type: line - connection: trs + connection: 1/4-inch maxConnections: 1 position: Left - name: X:FX Return R signalFlow: input category: audio type: line - connection: trs + connection: 1/4-inch maxConnections: 1 position: Left - name: Headphones Output (1/4") signalFlow: output category: audio type: headphone - connection: trs + connection: 1/4-inch maxConnections: 1 position: Right - name: Headphones Output (3.5mm) signalFlow: output category: audio type: headphone - connection: minijack + connection: 1/8-inch maxConnections: 1 position: Right links: diff --git a/data/hardware/artiphon-instrument-1.yaml b/data/hardware/artiphon-instrument-1.yaml index 5440415d8..69a348134 100644 --- a/data/hardware/artiphon-instrument-1.yaml +++ b/data/hardware/artiphon-instrument-1.yaml @@ -54,6 +54,6 @@ io: signalFlow: bidirectional category: digital type: usb - connection: mini-usb + connection: usb-b-mini maxConnections: 1 position: Bottom diff --git a/data/hardware/bastl-instruments-klik.yaml b/data/hardware/bastl-instruments-klik.yaml index a3301b6af..747275040 100644 --- a/data/hardware/bastl-instruments-klik.yaml +++ b/data/hardware/bastl-instruments-klik.yaml @@ -27,7 +27,7 @@ io: - name: Clock Output signalFlow: output category: audio - type: "cv/gate" + type: clock connection: 1/8-inch maxConnections: 1 position: Top diff --git a/data/hardware/mackie-dlm12.yaml b/data/hardware/mackie-dlm12.yaml index ab32c711c..b75b5e842 100644 --- a/data/hardware/mackie-dlm12.yaml +++ b/data/hardware/mackie-dlm12.yaml @@ -33,14 +33,14 @@ io: - name: Channel 1 Input signalFlow: input category: audio - type: line + type: mic connection: combo jack maxConnections: 1 position: Bottom - name: Channel 2 Input signalFlow: input category: audio - type: line + type: instrument connection: combo jack maxConnections: 1 position: Bottom diff --git a/docs/VALIDATION_ERRORS.md b/docs/VALIDATION_ERRORS.md index 6d559d115..d6e374b8b 100644 --- a/docs/VALIDATION_ERRORS.md +++ b/docs/VALIDATION_ERRORS.md @@ -288,7 +288,8 @@ receiver's BNC ports are `type: rf` (an antenna) with `connection: bnc` — not **Common mistakes:** -- `bnc`, `xlr`, `trs` -> connectors, not signals. Put them in `connection` and give `type` the actual signal (`rf`, `line`, `mic`) +- `bnc`, `xlr` -> connectors, not signals. Put them in `connection` and give `type` the actual signal (`rf`, `line`, `mic`) +- `trs` -> also a connector, and not a valid `connection` value either — use `connection: 1/4-inch` (or `1/8-inch`) and name the signal in `type` - `spdif` -> use `s/pdif` - `aes3`, `aes-ebu` -> use `aes/ebu` - `wordclock`, `word-clock` -> use `word clock` diff --git a/schema/CONTEXT.md b/schema/CONTEXT.md index 9250afbb1..cc397cfbd 100644 --- a/schema/CONTEXT.md +++ b/schema/CONTEXT.md @@ -848,6 +848,7 @@ rear-panel diagram — assign them with `pnpm enrich-io `, not during bulk - `usb-a` - `usb-b` - `usb-b-micro` +- `usb-b-mini` - `usb-c` - `thunderbolt 1` - `thunderbolt 2` diff --git a/schema/io-connections.yaml b/schema/io-connections.yaml index cb4de2317..1b5968771 100644 --- a/schema/io-connections.yaml +++ b/schema/io-connections.yaml @@ -30,6 +30,7 @@ connections: - usb-a - usb-b - usb-b-micro + - usb-b-mini - usb-c # Other digital connectors diff --git a/schema/io-types.yaml b/schema/io-types.yaml index 62e0f199e..cb7388882 100644 --- a/schema/io-types.yaml +++ b/schema/io-types.yaml @@ -44,7 +44,7 @@ types: # Control types - expression - cv/gate - - clock # modular sync/clock pulse (1/8-inch), distinct from `word clock` + - clock # modular sync/clock pulse, distinct from `word clock` - gpio # Wireless types