@openmixer/omx-contract 2.11.0 → 2.12.0

package/lib/fmt.mjs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
 /**
- * The one formatting of a data file (spec §3.2): two-space indent, one key per line, keys in schema
+ * The one formatting of a data file: two-space indent, one key per line, keys in schema
  * order, a trailing newline. Names (items, fields, sheet keys) keep the order the author gave them:
  * a travels table's field order is its C block order. A kernel file's sections come in their order (controls,
  * readouts, tables, aggregates, constants), its controls and readouts in the author's order, each one's keys in
@@ -12,7 +12,7 @@ const ORDER = {
   control: ['name', 'kind', 'global', 'table', 'rearms', 'since', 'doc', 'why', 'unit', 'ids', 'default', 'labels', 'travel', 'c'],
   sections: ['controls', 'readouts', 'tables', 'aggregates', 'constants'],
   readout: ['name', 'doc', 'unit', 'min', 'max', 'scale', 'rateHz'],
-  item: ['kind', 'since', 'doc', 'why', 'unit', 'value', 'values', 'ids', 'default', 'labels', 'fields', 'travel', 'c'],
+  item: ['kind', 'since', 'doc', 'why', 'unit', 'value', 'docs', 'values', 'ids', 'default', 'labels', 'fields', 'travel', 'codes', 'c'],
   travel: ['min', 'max', 'step', 'unit', 'default', 'defaultFrom', 'scale', 'byKind', 'doc', 'why'],
   c: ['alias', 'render'],
   alias: ['fact', 'field'],
@@ -48,6 +48,7 @@ function item(it) {
   if (!isObj(it)) return it;
   const o = ordered(it, ORDER.item);
   if ('value' in o) o.value = o.kind === 'sheet' ? sheet(o.value) : number(o.value);
+  if (isObj(o.codes)) o.codes = Object.fromEntries(Object.entries(o.codes).map(([k, c]) => [k, ordered(c, ['code', 'doc'])]));
   if (isObj(o.fields)) o.fields = Object.fromEntries(Object.entries(o.fields).map(([k, t]) => [k, isObj(t) ? travel(t) : t]));
   if (isObj(o.travel)) o.travel = travel(o.travel);
   if (isObj(o.c)) {

package/lib/semver.mjs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
 /**
- * `omx-contract semver`: classify every change between two resolved declarations (spec §3.6) and
+ * `omx-contract semver`: classify every change between two resolved declarations and
  * refuse a version whose bump is shorter than the largest class found.
  *
  *   major  a field or alias removed; an item removed (MINOR in the development phase, below); a
@@ -21,7 +21,7 @@
 const RANK = { none: 0, patch: 1, minor: 2, major: 3 };
 
 /**
- * The development-phase rule (omx-contract spec §3.6): while every consumer of
+ * The development-phase rule: while every consumer of
  * omx-contract is a FreeMixer repository named here, removing an item is MINOR. The rule ends, and
  * this becomes null so a removal is MAJOR again, in the release that names the first consumer
  * outside the list. Until then a MAJOR class is released as a minor bump (see refusal).
@@ -97,7 +97,7 @@ export function classify(prev, next, { developmentPhase = DEVELOPMENT_PHASE } =
     if (a.kind !== b.kind || (a.shape ?? '') !== (b.shape ?? '')) { say('major', `kind ${a.kind} -> ${b.kind}`); continue; }
     // a set that gains values gains their unit with them (minor, below); any other unit change is major
     if ((a.unit ?? '') !== (b.unit ?? '') && !(a.kind === 'set' && a.values === undefined)) say('major', `unit ${JSON.stringify(a.unit)} -> ${JSON.stringify(b.unit)}`);
-    if (a.doc !== b.doc || (a.why ?? '') !== (b.why ?? '')) say('patch', 'doc');
+    if (a.doc !== b.doc || (a.why ?? '') !== (b.why ?? '') || !same(a.docs, b.docs)) say('patch', 'doc');
     if (!same(a.c?.alias, b.c?.alias)) say(a.c?.alias ? 'major' : 'minor', a.c?.alias ? 'c.alias removed or renamed' : 'c.alias added');
     if (!same(a.c?.render, b.c?.render)) say(b.c?.render === false ? 'major' : 'minor', 'C render of the list changed');
     switch (a.kind) {
@@ -138,6 +138,14 @@ export function classify(prev, next, { developmentPhase = DEVELOPMENT_PHASE } =
           });
         }
         break;
+      case 'codes':
+        for (const k of Object.keys(a.value)) {
+          if (!(k in b.value)) say('major', `${name}.${k} removed`);
+          else if (a.value[k].code !== b.value[k].code) say('major', `${name}.${k}: ${JSON.stringify(a.value[k].code)} -> ${JSON.stringify(b.value[k].code)} (a code is read by verdicts, never reworded)`);
+          else if ((a.value[k].doc ?? '') !== (b.value[k].doc ?? '')) say('patch', `${name}.${k}: doc`);
+        }
+        for (const k of Object.keys(b.value)) if (!(k in a.value)) say('minor', `${name}.${k} added`);
+        break;
       default:
         break;
     }

package/lib/validate.mjs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
 /**
- * `omx-contract validate`: the schema, then the checks a schema cannot express (spec §3.3): every
+ * `omx-contract validate`: the schema, then the checks a schema cannot express: every
  * reference resolves with no cycle; every default inside its travel; every C name the render spells
  * is unique; an item's `c.alias` names no other item. Each failure names file, item and rule.
  */
@@ -127,6 +127,26 @@ function semanticRules(resolved, say) {
     }
   }
 
+  // A sheet's prose names fields the sheet has; a code is declared once.
+  for (const r of resolved.values()) {
+    if (r.kind === 'sheet' && r.docs !== undefined) {
+      for (const f of Object.keys(r.docs)) if (!(f in r.value)) say(r.rel, r.name, 'sheet-docs', `docs.${f} describes no field of ${r.name}`);
+    }
+    if (r.kind === 'codes') {
+      const seenCodes = new Map();
+      for (const [k, c] of Object.entries(r.value)) {
+        if (seenCodes.has(c.code)) say(r.rel, r.name, 'code-unique', `${k} and ${seenCodes.get(c.code)} both carry ${JSON.stringify(c.code)}`);
+        seenCodes.set(c.code, k);
+      }
+    }
+  }
+
+  // The hosted stage's limits are finite numbers, the header of the CLAP core reads each as a define.
+  const stage = resolved.get('HOSTED_STAGE_LIMITS');
+  if (stage) {
+    for (const [f, v] of Object.entries(stage.value)) if (typeof v !== 'number' || !Number.isFinite(v)) say(stage.rel, stage.name, 'finite', `HOSTED_STAGE_LIMITS.${f} resolves to ${JSON.stringify(v)}`);
+  }
+
   // A readout's numbers are finite, its range runs upward, its rate is positive and its scale is a PARAM_SCALES id.
   for (const [k, { readouts }] of Object.entries(resolved.kernels ?? {})) {
     for (const ro of readouts ?? []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmixer/omx-contract",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "The FreeMixer declarations as data: a JSON Schema, the data, and one CLI that renders them into C, TypeScript and JSON",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/render/c/clap-host-limits.mjs

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * `clap_host_limits.h`: the header the CLAP core (omx-clap-core) builds against and installs, rendered from
+ * `HOSTED_STAGE_LIMITS` and `HOSTING_CODES`. It is the library's API documentation too, so every define carries
+ * the prose declared beside its number or code as a trailing `///<` comment; the frame below is the only prose
+ * here. The fields named `worker*` are the LV2 adapter's and are not rendered.
+ */
+
+const constCase = (s) => String(s).replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+
+/** The licence block every source file of omx-clap-core opens with: the SPDX line, the GPL notice, the copyright line, a blank line. */
+const LICENCE = `/* SPDX-License-Identifier: GPL-3.0-or-later */
+/*
+ * This file is part of omx-clap-host.
+ *
+ * omx-clap-host is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * omx-clap-host is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with omx-clap-host.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+ */
+
+`;
+
+const isLevel = (field) => field.endsWith('Dbfs');
+
+/** A define with its prose as a trailing member comment; a one-line prose only, or the rest would be read as C. */
+function documented(define, prose, where) {
+  if (prose === undefined) return define;
+  if (typeof prose !== 'string' || prose.length === 0 || /[\n\r]/.test(prose)) throw new Error(`clap-host-limits: ${where} is no one-line description`);
+  return `${define}  ///< ${prose}`;
+}
+
+/** The header of the resolved items `HOSTED_STAGE_LIMITS` and `HOSTING_CODES`. */
+export function renderClapHostLimits(stage, codes) {
+  const numbers = Object.entries(stage.value)
+    .filter(([field]) => !field.startsWith('worker'))
+    .map(([field, v]) => {
+      if (typeof v !== 'number' || !Number.isFinite(v)) throw new Error(`clap-host-limits: HOSTED_STAGE_LIMITS.${field} is not a finite number`);
+      const literal = isLevel(field) ? `${Number.isInteger(v) ? `${v}.0` : v}f` : Number.isInteger(v) && v >= 0 ? `${v}u` : null;
+      if (literal === null) throw new Error(`clap-host-limits: HOSTED_STAGE_LIMITS.${field} is neither a level (Dbfs) nor a non-negative integer`);
+      return documented(`#define CLAP_HOST_${constCase(field)} ${literal}`, stage.docs?.[field], `HOSTED_STAGE_LIMITS.docs.${field}`);
+    });
+  const refusals = Object.entries(codes.value)
+    .map(([name, c]) => documented(`#define CLAP_HOST_CODE_${constCase(name)} ${JSON.stringify(c.code)}`, c.doc, `HOSTING_CODES.${name}.doc`));
+  return `${LICENCE}#ifndef CLAP_HOST_LIMITS_H
+#define CLAP_HOST_LIMITS_H
+/*
+ * GENERATED — DO NOT EDIT BY HAND.
+ * Rendered by \`omx-contract render --target c\` from FreeMixer/omx-contract's HOSTED_STAGE_LIMITS and
+ * HOSTING_CODES. The rendered file is kept in this repository so the library builds on its own; the numbers
+ * and codes are changed where they are declared and the file is re-rendered, never edited here.
+ */
+
+/** @file
+ * @brief The limits and refusal codes of the hosting code. */
+
+#include <stddef.h>
+
+/** the stage and the host: every number the core reads */
+${numbers.join('\n')}
+
+/** the refusals the core returns, as the hosting codes the console's verdicts use */
+${refusals.join('\n')}
+
+#endif /* CLAP_HOST_LIMITS_H */
+`;
+}

package/render/c.mjs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
 /**
- * The `c` target: `omxcontract/omx_contract_limits.h`. Every define is spelled by openmixer's
+ * The `c` target: `omxcontract/omx_contract_limits.h`, and `omxcontract/clap_host_limits.h` where the data declares the hosting limits and codes (docs/hosting.md). Every define is spelled by the console engine's
  * renderer, moved unchanged (c/contract-limits-render.mjs); only the frame (banner, section
  * comments) is this repository's. A plugin's parameter header is rendered by omx-plugins from its
  * declaration, by reference to the items here.
@@ -10,11 +10,12 @@ import {
   cStringLiteral, genCoreLimitBlock, genDeclaredListsBlock, genDeclaredRates, genDeclaredScalarsBlock, genLimitBlock, renderContractLimits,
   scalarLiteral,
 } from './c/contract-limits-render.mjs';
+import { renderClapHostLimits } from './c/clap-host-limits.mjs';
 import { doors } from './doors.mjs';
 
 const defined = (text) => new Set([...text.matchAll(/^#define (OMX_\w+)/gm)].map((m) => m[1]));
 
-/** The rate tail of openmixer's header, outside the include guard, byte for byte. */
+/** The rate tail of the console engine's header, outside the include guard, byte for byte. */
 function ratesTail(rates) {
   return `
 /* The sample rates the console declares (core's STANDARD_SAMPLE_RATES, row-codecs.ts): the set a
@@ -193,12 +194,16 @@ ${d.STANDARD_SAMPLE_RATES ? ratesTail(d.STANDARD_SAMPLE_RATES) : ''}`;
 
 /** Every file of the `c` target: `[{ path, text }]`, paths relative to the output directory. */
 export function renderC(resolved) {
-  return [{ path: 'omxcontract/omx_contract_limits.h', text: renderLimitsHeader(resolved) }];
+  const files = [{ path: 'omxcontract/omx_contract_limits.h', text: renderLimitsHeader(resolved) }];
+  const stage = resolved.get('HOSTED_STAGE_LIMITS');
+  const codes = resolved.get('HOSTING_CODES');
+  if (stage && codes) files.push({ path: 'omxcontract/clap_host_limits.h', text: renderClapHostLimits(stage, codes) });
+  return files;
 }
 
 /**
- * The `c` target of a frozen openmixer sheet (test/fixtures/): `{ sheet }` rendered by openmixer's own
- * renderer, for the round-trip proof (spec §4.4 step 1).
+ * The `c` target of a frozen sheet (test/fixtures/frozen-limits-sheet.json): `{ sheet }` rendered by the moved
+ * renderer, for the round-trip proof.
  */
 export function renderSheetC(fixture) {
   const s = fixture.sheet;

package/render/ts.mjs

@@ -4,7 +4,7 @@ import { eqDefaultBands, eqDefaultCentres, eqDefaultParams, eqDefaultTypes } fro
 
 /**
  * The `ts` target: one ESM module and its type declarations, every item exported under its own
- * name with its literal type (`as const`), so a re-export in openmixer keeps names, values and types.
+ * name with its literal type (`as const`), so a consumer's re-export keeps names, values and types.
  */
 
 /** The value a TypeScript reader sees for one resolved item. */

package/schema/omx-contract.schema.json

@@ -12,7 +12,7 @@
   "$defs": {
     "unit": {
       "description": "The closed list of units the items use; \"x\" is a multiplier, \"\" is a ratio or a fraction.",
-      "enum": ["dB", "dBFS", "ms", "s", "min", "Hz", "oct", "cents", "%", "x", ""]
+      "enum": ["dB", "dBFS", "ms", "s", "min", "Hz", "oct", "cents", "st", "%", "x", ""]
     },
     "text": { "type": "string", "minLength": 1 },
     "since": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "The release that first carried an item declared outside the kernels (rates.json, primitives.json); a kernel's items record it in recipes/answers/." },
@@ -156,7 +156,14 @@
         "since": { "$ref": "#/$defs/since" },
         "doc": { "$ref": "#/$defs/text" },
         "why": { "$ref": "#/$defs/text" },
-        "value": { "$ref": "#/$defs/sheetValue" }
+        "value": { "$ref": "#/$defs/sheetValue" },
+        "docs": {
+          "description": "One line of prose per top-level field of `value`, rendered beside the field's define in a header that documents it. A field without one has none.",
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z][A-Za-z0-9]*$" },
+          "additionalProperties": { "$ref": "#/$defs/text" },
+          "minProperties": 1
+        }
       },
       "required": ["kind", "doc", "value"],
       "additionalProperties": false
@@ -179,6 +186,32 @@
       "required": ["kind", "doc", "unit", "values"],
       "additionalProperties": false
     },
+    "codes": {
+      "type": "object",
+      "description": "Refusal codes: a lowerCamel name per code, the code itself (`hosting.<group>.<reason>`, lower case, read by verdicts and never reworded) and optionally one line of prose.",
+      "properties": {
+        "kind": { "const": "codes" },
+        "since": { "$ref": "#/$defs/since" },
+        "doc": { "$ref": "#/$defs/text" },
+        "why": { "$ref": "#/$defs/text" },
+        "codes": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z][A-Za-z0-9]*$" },
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "code": { "type": "string", "pattern": "^hosting(\\.[a-z0-9]+(-[a-z0-9]+)*){2,}$" },
+              "doc": { "$ref": "#/$defs/text" }
+            },
+            "required": ["code"],
+            "additionalProperties": false
+          },
+          "minProperties": 1
+        }
+      },
+      "required": ["kind", "doc", "codes"],
+      "additionalProperties": false
+    },
     "set": {
       "type": "object",
       "description": "Ordered ids with an optional default, labels and a value per id. The ids and their order are the contract: all strings of letters and digits (the id is the name, its position the value; an id may start with a digit, as 4x does) or all non-negative integers (the id is the value). Labels are face text and optional. The default may be a reference to the scalar that states it: a boolean names the second id of a two-id switch when true, the first when false.",
@@ -210,13 +243,14 @@
     "item": {
       "type": "object",
       "required": ["kind"],
-      "properties": { "kind": { "enum": ["scalar", "travels", "sheet", "list", "set"] } },
+      "properties": { "kind": { "enum": ["scalar", "travels", "sheet", "list", "set", "codes"] } },
       "allOf": [
         { "if": { "properties": { "kind": { "const": "scalar" } } }, "then": { "$ref": "#/$defs/scalar" } },
         { "if": { "properties": { "kind": { "const": "travels" } } }, "then": { "$ref": "#/$defs/travels" } },
         { "if": { "properties": { "kind": { "const": "sheet" } } }, "then": { "$ref": "#/$defs/sheet" } },
         { "if": { "properties": { "kind": { "const": "list" } } }, "then": { "$ref": "#/$defs/list" } },
-        { "if": { "properties": { "kind": { "const": "set" } } }, "then": { "$ref": "#/$defs/set" } }
+        { "if": { "properties": { "kind": { "const": "set" } } }, "then": { "$ref": "#/$defs/set" } },
+        { "if": { "properties": { "kind": { "const": "codes" } } }, "then": { "$ref": "#/$defs/codes" } }
       ]
     }
   }