motionspec 1.0.3 → 1.0.4

package/README.md

@@ -22,7 +22,7 @@ request ──> Routing (small model, Stage A) ──> MotionSpec (JSON)
 |---|---|
 | Version | **v1.0.3** · schema frozen at spec v1 (ADR-0001, signed) |
 | Published | **npm `motionspec`** · MCP Registry `io.github.MasterPlayspots/motionspec` |
-| Tests | **155** green · CI on Node 18/20/22 |
+| Tests | **177** green · CI on Node 18/20/22 |
 | Catalog | **8** primitives, all device-verified |
 | Dependencies | **0 vulnerabilities** · SBOM committed · all permissive licenses |
 | Coverage | **98.4% lines / 95.9% functions** of `src/` + `worker/` (CI gate fails under 90%) |
@@ -51,7 +51,7 @@ Listed on the MCP Registry as `io.github.MasterPlayspots/motionspec`.
 
 ```bash
 npm ci                                      # install (0 runtime deps beyond MCP SDK + zod)
-npm test                                    # 151 tests: validator, compiler-golden, router, fuzz, schema parity, worker contract
+npm test                                    # 177 tests: validator, compiler-golden, router, fuzz, schema parity, worker contract
 node bin/motion.js catalog                  # primitives + catalog version (16-char hash)
 node bin/motion.js compile examples/hero.motionspec.json
 node bin/motion.js pipeline "Hero headline fades in, cards staggered" --mock
@@ -87,7 +87,7 @@ Tools: `motion_catalog` (primitives + authoring rules) · `motion_validate` (fai
 
 1. **Allow-list** — a primitive not in the catalog never reaches the compiler.
 2. **Injection-proof** — ids, selectors, string params and triggers are charset-validated; every interpolation is a JS literal (`JSON.stringify`) or a CSS-screened raw value. Malicious model output is rejected fail-closed (tested + fuzzed over 6000 random specs).
-3. **a11y** — `respectReducedMotion` gates JS and CSS; the model cannot switch it off.
+3. **a11y** — `respectReducedMotion` is **default-on at the compiler level** (fail-safe): omitting `globals` or the field yields a `prefers-reduced-motion` guard. Setting `globals.respectReducedMotion: false` is accepted but emits a compiler warning (`MS-GLOBALS-RRM-OFF`); a prompt-only instruction is not sufficient to disable the guard.
 4. **Determinism** — same spec ⇒ identical code (golden-file tests).
 5. **Versioned** — schema frozen v1; catalog SemVer enforced by a diff-gate; specs may pin `catalogVersion` for reproducibility (`MS-CATALOG-PIN-MISMATCH` fail-closed).
 6. **Observability** — every request logs `model | model-repaired | cache-hit | escalate-*` to `telemetry/events.jsonl`; escalation clusters are the signal for new primitives (concept §3.3).
@@ -102,7 +102,7 @@ src/compiler/    catalog.js · catalog-semver.js · validate.js (Trust Boundary)
 src/router/      prompt.js · clients.js (openai-compat + mock) · route.js · cache.js · telemetry.js
 src/mcp/         server.mjs (4 tools, fail-closed, input-capped)
 bin/             motion.js (CLI) · catalog-lock.js · license-check.js
-test/            151 tests incl. injection attacks, fuzz, golden files, schema parity, worker contract; test/e2e (Playwright)
+test/            177 tests incl. injection attacks, fuzz, golden files, schema parity, worker contract; test/e2e (Playwright)
 docs/            ADR-0001 (schema freeze) · ROADMAP_TO_10 · PHASE_A_REAUDIT · CLAUDE_CODE_HANDOFF
 ```
 
@@ -115,6 +115,12 @@ Concept, research, pitch, business docs and the CHS client site live in the sibl
 - `docs/adr/0001-schema-freeze-v1.md` — the frozen v1 contract and why.
 - `docs/PHASE_A_REAUDIT_2026-06-15.md` — independent re-audit findings + fixes.
 
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the
+gate-driven PR checklist, commit conventions, and a short architecture tour. Bug
+reports and feature requests have issue templates under `.github/ISSUE_TEMPLATE/`.
+
 ## License
 
 MIT.

package/bin/motion.js

@@ -79,7 +79,7 @@ async function main() {
   }
 
   if (cmd === "stats") {
-    const s = telemetry.summary();
+    const s = await telemetry.summary();
     console.log("Telemetrie: " + s.total + " Ereignisse");
     Object.keys(s.byOutcome).forEach((k) => console.log("  " + k + ": " + s.byOutcome[k]));
     return;

package/bin/sbom-check.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * SBOM-Werkzeug (TASK-021, Audit-Befund #13). Zero-dep, CJS.
+ *
+ * Hintergrund: `npm sbom --omit dev` laesst hier 9 Laufzeit-Pakete aus
+ * (cross-spawn, debug, ms, which, isexe, path-key, shebang-command,
+ * shebang-regex, fast-deep-equal) — sie haengen am Prod-Baum von
+ * @modelcontextprotocol/sdk, werden aber, weil sie ZUSAETZLICH ueber einen
+ * dev-Pfad (eslint) erreichbar sind, von npm faelschlich weggeschnitten. Das
+ * Lizenz-Gate war dadurch lueckenhaft. Gleichzeitig darf die SBOM keine reinen
+ * dev-Pakete (wrangler/eslint/…) enthalten, weil deren Lizenzen das Gate sonst
+ * (zu Recht) rot faerben und nicht ausgeliefert werden.
+ *
+ * Loesung: die VOLLE SBOM erzeugen und auf die LAUFZEIT-Pakete filtern
+ * (Quelle der Wahrheit: package-lock.json, top-level node_modules/* mit
+ * dev!==true). Das ergibt eine vollstaendige UND ausschliesslich-Laufzeit-SBOM.
+ *
+ * Modi:
+ *   --filter   liest eine volle CycloneDX-SBOM von stdin, schreibt die
+ *              Laufzeit-gefilterte SBOM nach stdout (genutzt vom `sbom`-Script).
+ *   (default)  prueft sbom.cdx.json: jedes Laufzeit-Paket MUSS als Komponente
+ *              vorhanden sein; fehlt eines -> Liste + exit 1, sonst exit 0.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const LOCK = path.join(ROOT, "package-lock.json");
+const SBOM = path.join(ROOT, "sbom.cdx.json");
+
+/* Laufzeit-Pakete laut Lockfile: top-level node_modules/<name>, dev !== true.
+ * Liefert ein Set voller Namen (inkl. @scope). */
+function runtimeNames() {
+  const lock = JSON.parse(fs.readFileSync(LOCK, "utf8"));
+  const names = new Set();
+  for (const key of Object.keys(lock.packages || {})) {
+    const m = /^node_modules\/(@[^/]+\/[^/]+|[^/]+)$/.exec(key);
+    if (!m) continue;                       // nur top-level (keine verschachtelten Dubletten)
+    if (lock.packages[key].dev === true) continue;  // reine dev-Pakete weglassen
+    names.add(m[1]);
+  }
+  return names;
+}
+
+/* Voller Name einer CycloneDX-Komponente (npm legt @scope direkt in name, aber
+ * group wird defensiv mitgenommen, falls ein Generator es doch trennt). */
+function compName(c) {
+  return c.group ? c.group + "/" + c.name : c.name;
+}
+
+function readStdin() {
+  return fs.readFileSync(0, "utf8");
+}
+
+function filterMode() {
+  const full = JSON.parse(readStdin());
+  const runtime = runtimeNames();
+  const keep = (full.components || []).filter((c) => runtime.has(compName(c)));
+  const keptRefs = new Set(keep.map((c) => c["bom-ref"]).filter(Boolean));
+  full.components = keep;
+  /* Abhaengigkeits-Graph auf behaltene Komponenten beschneiden, damit keine
+   * baumelnden Referenzen zurueckbleiben (die Wurzel-Komponente bleibt). */
+  if (Array.isArray(full.dependencies)) {
+    const rootRef = full.metadata && full.metadata.component && full.metadata.component["bom-ref"];
+    full.dependencies = full.dependencies
+      .filter((d) => d.ref === rootRef || keptRefs.has(d.ref))
+      .map((d) => Array.isArray(d.dependsOn)
+        ? Object.assign({}, d, { dependsOn: d.dependsOn.filter((r) => r === rootRef || keptRefs.has(r)) })
+        : d);
+  }
+  process.stdout.write(JSON.stringify(full, null, 2) + "\n");
+}
+
+function checkMode() {
+  if (!fs.existsSync(SBOM)) { console.error("Keine sbom.cdx.json — erst `npm run sbom`."); process.exit(1); }
+  const sbom = JSON.parse(fs.readFileSync(SBOM, "utf8"));
+  const present = new Set((sbom.components || []).map(compName));
+  const missing = [...runtimeNames()].filter((n) => !present.has(n)).sort();
+  if (missing.length) {
+    console.error("SBOM unvollstaendig — " + missing.length + " Laufzeit-Paket(e) fehlen:");
+    missing.forEach((n) => console.error("  - " + n));
+    console.error("Fix: `npm run sbom` neu erzeugen (vollstaendige Laufzeit-SBOM).");
+    process.exit(1);
+  }
+  console.error("SBOM OK — alle " + present.size + " Komponenten decken die Laufzeit-Pakete ab.");
+}
+
+if (process.argv.includes("--filter")) filterMode();
+else checkMode();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motionspec",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "mcpName": "io.github.MasterPlayspots/motionspec",
   "description": "MotionSpec — a formal intermediate language for scroll-driven web motion. A small model writes schema-validated specs; a deterministic compiler emits GSAP/CSS, hallucination-proof by construction with enforced reduced-motion fallbacks.",
   "license": "MIT",
@@ -41,7 +41,8 @@
     "test": "node --test test/validate.test.js test/compile.test.js test/specversion-v1.test.js test/route.test.js test/route-live.test.js test/catalog-wave1.test.js test/catalog-semver.test.js test/schema-parity.test.js test/catalog-pin.test.js test/css-safety.test.js test/fuzz.test.js test/hardening.test.js test/cache.test.js test/errorcodes.test.js test/catalog-integrity.test.js test/discover.test.js test/telemetry-sink.test.js test/worker-contract.test.mjs test/analytics-engine-sink.test.mjs test/canary.test.mjs test/dashboard.test.mjs test/mcp.test.mjs test/cli-output.test.mjs",
     "coverage": "node --test --experimental-test-coverage --test-coverage-exclude=test/** --test-coverage-exclude=bin/** --test-coverage-lines=90 --test-coverage-functions=90 --test-coverage-branches=75 test/*.test.js test/*.test.mjs",
     "e2e": "playwright test",
-    "sbom": "npm sbom --sbom-format cyclonedx --omit dev > sbom.cdx.json",
+    "sbom": "npm sbom --sbom-format cyclonedx | node bin/sbom-check.js --filter > sbom.cdx.json",
+    "sbom:check": "node bin/sbom-check.js",
     "catalog-lock": "node bin/catalog-lock.js",
     "catalog-lock:check": "node bin/catalog-lock.js --check",
     "mcp": "node src/mcp/server.mjs",
@@ -51,20 +52,25 @@
     "pipeline": "node bin/motion.js pipeline",
     "catalog": "node bin/motion.js catalog",
     "stats": "node bin/motion.js stats",
-    "prepublishOnly": "npm test && npm run catalog-lock:check && npm run sbom && node bin/license-check.js",
-    "lint": "eslint ."
+    "prepublishOnly": "npm test && npm run catalog-lock:check && npm run sbom && npm run sbom:check && node bin/license-check.js && node -e \"if(!require('fs').existsSync('CHANGELOG.md'))throw new Error('CHANGELOG.md fehlt')\"",
+    "lint": "eslint .",
+    "prepare": "husky"
   },
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
-    "zod": "^4.4.3"
+    "zod": "4.4.3"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.50.0",
     "eslint": "^10.5.0",
-    "globals": "^17.6.0"
+    "globals": "^17.6.0",
+    "husky": "^9.1.7",
+    "wrangler": "4.103.0"
   }
 }

package/schema/motionspec.schema.json

@@ -35,9 +35,9 @@
         "additionalProperties": false,
         "required": ["id", "primitive", "target"],
         "properties": {
-          "id": { "type": "string", "minLength": 1 },
+          "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" },
           "primitive": { "type": "string", "description": "Muss ein Name aus dem Primitive-Katalog sein. Allow-List, zur Laufzeit geprueft." },
-          "target": { "type": "string", "minLength": 1 },
+          "target": { "type": "string", "minLength": 1, "maxLength": 200 },
           "params": { "type": "object" },
           "trigger": {
             "type": "object",

package/src/compiler/catalog.js

@@ -91,4 +91,30 @@ function catalogVersion(catalog) {
   return crypto.createHash("sha256").update(stable).digest("hex").slice(0, 16);
 }
 
-module.exports = { loadCatalog, buildCatalog, catalogVersion, checkPrimitive };
+/* Gemeinsame Katalog-Zusammenfassung (TASK-026, Audit #23). Vorher gab es zwei
+ * divergierende Implementierungen (prompt.js 4 Felder, register-tools.js 8). Eine
+ * Quelle: Default sind alle 8 Felder; ein optionales fields-Subset liefert weniger
+ * (z.B. fuer einen schlankeren Prompt). Primitive nach Namen sortiert. */
+function catalogSummary(catalog, fields) {
+  const ALL = ["name", "version", "purpose", "engine", "cost", "paramSchema", "triggerDefaults", "reducedMotionFallback"];
+  const pick = Array.isArray(fields) ? fields : ALL;
+  return Object.keys(catalog).sort().map((name) => {
+    const p = catalog[name];
+    const full = {
+      name,
+      version: p.version,
+      purpose: p.purpose,
+      engine: p.engine,
+      cost: (p.performance && p.performance.cost) || 0,
+      paramSchema: p.paramSchema || {},
+      triggerDefaults: p.triggerDefaults || {},
+      reducedMotionFallback: (p.a11y && p.a11y.reducedMotionFallback) || null,
+    };
+    if (pick === ALL) return full;
+    const o = {};
+    pick.forEach((f) => { o[f] = full[f]; });
+    return o;
+  });
+}
+
+module.exports = { loadCatalog, buildCatalog, catalogVersion, checkPrimitive, catalogSummary };

package/src/compiler/compile.js

@@ -62,10 +62,35 @@ function withDefaults(schema, given) {
   return out;
 }
 
-/*
- * compileSpec(spec, catalog, opts) -> {
- *   ok, errors?, js?, css?, report: { motions, jsCount, cssCount,
- *   cost, budget, budgetOk, reducedMotion } }
+/**
+ * @typedef {Object} CompileReport
+ * @property {number} motions - Anzahl kompilierter Motions
+ * @property {number} jsCount - Anzahl JS-Ausgaben
+ * @property {number} cssCount - Anzahl CSS-Ausgaben
+ * @property {number} cost - Summe der Primitiv-Kosten
+ * @property {number} budget - Performance-Budget (Default BUDGET)
+ * @property {boolean} budgetOk - true wenn cost <= budget
+ * @property {boolean} reducedMotion - ob ein prefers-reduced-motion-Guard emittiert wird
+ * @property {boolean} reducedMotionOverriddenOff - true wenn die Spec den Guard explizit abschaltet
+ * @property {string} specVersion - specVersion der Quelle
+ * @property {Array<{code:string,message:string}>} deprecations - Deprecation-Hinweise (ADR-0001 D4)
+ */
+/**
+ * @typedef {Object} CompileResult
+ * @property {boolean} ok - true bei Erfolg, false fail-closed (keine Teil-Ausgabe)
+ * @property {string[]} [errors] - Fehler mit [MS-XXX]-Praefix, nur wenn ok=false
+ * @property {string|null} [js] - generiertes JS (null wenn keine JS-Motions)
+ * @property {string|null} [css] - generiertes CSS (null wenn keine CSS-Motions)
+ * @property {CompileReport} [report] - Report, nur wenn ok=true
+ */
+/**
+ * Validiert (fail-closed) und kompiliert eine MotionSpec deterministisch zu GSAP/CSS.
+ * Dieselbe Spec ergibt immer denselben Code; bei Validierungs- oder CSS-Fehlern
+ * wird nichts emittiert.
+ * @param {Object} spec - die MotionSpec
+ * @param {Object} catalog - geladener Primitiv-Katalog
+ * @param {{specName?: string, budget?: number}} [opts] - optionaler Artefakt-Name + Budget
+ * @returns {CompileResult}
  */
 function compileSpec(spec, catalog, opts) {
   const o = opts || {};
@@ -77,7 +102,7 @@ function compileSpec(spec, catalog, opts) {
    * so validate-only callers and the compile report agree. */
   const deprecations = v.deprecations || [];
 
-  const respectRM = !!(spec.globals && spec.globals.respectReducedMotion);
+  const respectRM = !(spec.globals && spec.globals.respectReducedMotion === false);
   const js = [], css = [];
   let cost = 0, nJs = 0, nCss = 0;
 
@@ -140,6 +165,7 @@ function compileSpec(spec, catalog, opts) {
       budget,
       budgetOk: cost <= budget,
       reducedMotion: respectRM,
+      reducedMotionOverriddenOff: !!(spec.globals && spec.globals.respectReducedMotion === false),
       specVersion: spec.specVersion,
       deprecations,
     },

package/src/compiler/keyword-map.js

@@ -0,0 +1,26 @@
+"use strict";
+/*
+ * Gemeinsame Keyword->Primitiv-Heuristik (TASK-025, Audit #22).
+ *
+ * Vorher gab es ZWEI divergierende Tabellen: clients.js (mockClient, 5 Eintraege,
+ * mit target/params) und discover.js (Gap-Report, 8 Eintraege, ohne target). Dadurch
+ * fehlten counterUp/marquee/scaleOnScroll im Mock — der Repair-Loop lief gegen ein
+ * kuenstlich unvollstaendiges Modell. Eine Quelle der Wahrheit schliesst die Luecke.
+ *
+ * Quelle der Regex/Reihenfolge ist discover.js (der vollstaendigere 8er-Satz);
+ * target/params der fuenf bekannten Primitive stammen aus clients.js, fuer die drei
+ * neuen sind sinnvolle Default-Selektoren gesetzt. WICHTIG: Reihenfolge ist API —
+ * discover.mapIntent() liefert den ERSTEN Treffer, daher Eintraege nicht umsortieren.
+ */
+const KEYWORD_MAP = [
+  { re: /(stagger|nacheinander|gestaffelt|one after|cards?|karten|liste)/i, primitive: "staggerReveal", target: ".features .card", params: { from: { opacity: 0, y: 32 } } },
+  { re: /(z(ä|ae)hl|counter|hochz(ä|ae)hl|count up|nummer|zahl)/i, primitive: "counterUp", target: ".stats .num", params: {} },
+  { re: /(parallax|tiefe|depth|layer|ebene)/i, primitive: "parallaxLayer", target: ".hero .bg", params: { yPercent: -25 } },
+  { re: /(pin|fixier|sticky|festhalten|haften)/i, primitive: "pinnedSection", target: ".showcase", params: { distance: "+=100%" } },
+  { re: /(marquee|laufband|logo.?band|ticker|endlos)/i, primitive: "marquee", target: ".marquee-track", params: {} },
+  { re: /(skalier|scale|zoom|gr(ö|oe)(ß|ss)er werden)/i, primitive: "scaleOnScroll", target: ".section", params: {} },
+  { re: /(hover|maus|cursor|button)/i, primitive: "cssTransition", target: ".cta-button", params: { hoverValue: "translateY(-4px)" } },
+  { re: /(reveal|einblend|fade|erscheinen|appear|headline|(ü|ue)berschrift|gleitet|scroll)/i, primitive: "scrollReveal", target: ".hero h1", params: { from: { opacity: 0, y: 48 } } },
+];
+
+module.exports = { KEYWORD_MAP };

package/src/compiler/validate.js

@@ -49,6 +49,10 @@
  *   MS-DEPRECATED-VERSION specVersion ist deprecated. KEIN harter Fehler:
  *                     wird in validateSpec().deprecations[] UND im Compile-Report
  *                     gemeldet (gemeinsame Quelle deprecationsFor; ADR-0001 D4).
+ *   MS-GLOBALS-RRM-OFF  globals.respectReducedMotion ist explizit false — Compiler
+ *                     emittiert keinen prefers-reduced-motion-Guard. Kein harter
+ *                     Fehler, aber Warnung (in validateSpec().warnings[]).
+ *   MS-INPUT-TOO-LARGE  Spec-Payload > MAX_SPEC_BYTES (64KB), MCP-Layer.
  */
 
 /* ADR-0001 (signed 2026-06-15): v1 carries "1.0". "0.1" stays accepted for
@@ -71,6 +75,7 @@ const TOP_KEYS = ["specVersion", "catalogVersion", "meta", "globals", "motions"]
 const CATALOG_PIN_RE = /^[0-9a-f]{16}$/;
 const META_KEYS = ["project", "target", "createdWith"];
 const GLOBALS_KEYS = ["respectReducedMotion", "defaultEase"];
+// defaultEase: allowlisted, aber vom Compiler aktuell nicht ausgewertet — belassen um Specs nicht zu brechen (TASK-017)
 const MOTION_KEYS = ["id", "primitive", "target", "params", "trigger", "responsive"];
 
 const { catalogVersion } = require("./catalog.js");
@@ -165,14 +170,103 @@ function validateTrigger(trigger, at, push) {
     push("MS-TRIGGER-VAL", at + ": trigger.once muss true oder false sein.");
 }
 
+/* TASK-027: kohaerente Teil-Validatoren aus validateSpec extrahiert (Verhalten
+ * identisch) — so bleibt validateSpec flach und jeder Teil ist einzeln testbar.
+ * Keiner davon wird exportiert; das oeffentliche Interface bleibt validateSpec. */
+function validateCatalogPin(spec, catalog, push) {
+  /* ADR-0001 D2: optionaler catalogVersion-Pin fuer Reproduzierbarkeit. Pinnt
+   * eine Spec einen Hash, MUSS er zum geladenen Katalog passen — fail-closed. */
+  if (spec.catalogVersion === undefined) return;
+  if (typeof spec.catalogVersion !== "string" || !CATALOG_PIN_RE.test(spec.catalogVersion)) {
+    push("MS-CATALOG-PIN", "catalogVersion muss ein 16-stelliger Hex-Hash sein (oder weglassen).");
+    return;
+  }
+  const actual = catalogVersion(catalog);
+  if (spec.catalogVersion !== actual)
+    push("MS-CATALOG-PIN-MISMATCH", "catalogVersion-Pin (" + spec.catalogVersion + ") passt nicht zum geladenen Katalog (" + actual + "). Spec wurde gegen einen anderen Katalog geschrieben.");
+}
+
+function validateMeta(spec, push) {
+  if (!spec.meta || typeof spec.meta !== "object") { push("MS-META-MISSING", "meta fehlt."); return; }
+  Object.keys(spec.meta).forEach((k) => {
+    if (META_KEYS.indexOf(k) === -1) push("MS-META-KEY", 'meta: unbekannter Schluessel "' + k + '".');
+  });
+  if (TARGETS.indexOf(spec.meta.target) === -1)
+    push("MS-META-TARGET", "meta.target fehlt oder wird nicht unterstuetzt (erlaubt: " + TARGETS.join(", ") + ").");
+}
+
+function validateGlobals(spec, push, warnings) {
+  if (spec.globals === undefined) return;
+  if (typeof spec.globals !== "object" || spec.globals === null || Array.isArray(spec.globals)) {
+    push("MS-GLOBALS-OBJ", "globals muss ein Objekt sein.");
+    return;
+  }
+  Object.keys(spec.globals).forEach((k) => {
+    if (GLOBALS_KEYS.indexOf(k) === -1) push("MS-GLOBALS-KEY", 'globals: unbekannter Schluessel "' + k + '" (erlaubt: ' + GLOBALS_KEYS.join(", ") + ").");
+  });
+  if (spec.globals.respectReducedMotion === false)
+    warnings.push({ code: "MS-GLOBALS-RRM-OFF", message: "globals.respectReducedMotion ist explizit false — Compiler emittiert keinen prefers-reduced-motion-Guard. Empfehlung: true." });
+}
+
+/* Validiert EINE Motion (TASK-027: aus validateSpec extrahiert, damit validateSpec
+ * flach und gut testbar bleibt — Verhalten identisch). `seen` wird geteilt, damit
+ * die id-Eindeutigkeit ueber alle Motions hinweg greift. Bewusst NICHT exportiert. */
+function validateMotion(m, i, catalog, push, seen) {
+  const at = "motions[" + i + "]";
+  if (typeof m !== "object" || m === null) { push("MS-MOTION-OBJ", at + " ist kein Objekt."); return; }
+
+  Object.keys(m).forEach((k) => {
+    if (MOTION_KEYS.indexOf(k) === -1) push("MS-MOTION-KEY", at + ': unbekannter Schluessel "' + k + '".');
+  });
+
+  if (typeof m.id !== "string" || !ID_RE.test(m.id))
+    push("MS-ID-FORMAT", at + ": id fehlt oder verletzt das Format [A-Za-z0-9_-]{1,64}.");
+  else if (seen[m.id]) push("MS-ID-DUP", at + ': id "' + m.id + '" ist nicht eindeutig.');
+  else seen[m.id] = true;
+
+  if (!safeSelector(m.target))
+    push("MS-TARGET-UNSAFE", at + ": target fehlt oder ist kein sicherer CSS-Selektor (verboten: Quotes, Backslash, {, }, ;, @, Steuerzeichen; max. 200 Zeichen).");
+
+  /* --- Kern-Schutz: Primitive-Allow-List --- */
+  if (typeof m.primitive !== "string" || !m.primitive) {
+    push("MS-PRIM-MISSING", at + ": primitive fehlt.");
+  } else if (!catalog[m.primitive]) {
+    push("MS-PRIM-UNKNOWN", at + ': primitive "' + m.primitive + '" existiert nicht im Katalog. '
+      + "Erlaubt sind ausschliesslich: " + Object.keys(catalog).sort().join(", ") + ".");
+  } else {
+    const prim = catalog[m.primitive];
+    validateParams(prim, m.params || {}, at, push, false);
+    if (m.trigger !== undefined) validateTrigger(m.trigger, at, push);
+    if (m.responsive !== undefined) {
+      push("MS-RESP-UNSUPPORTED", at + ": responsive wird in dieser specVersion noch nicht unterstuetzt (geplant fuer 0.2). Feld entfernen.");
+    }
+  }
+}
+
+/**
+ * @typedef {Object} ValidationResult
+ * @property {boolean} ok - true wenn die Spec jede Pruefung besteht (fail-closed)
+ * @property {string[]} errors - menschenlesbare Fehler, jeweils mit [MS-XXX]-Praefix
+ * @property {string[]} errorCodes - die reinen Codes, index-parallel zu errors
+ * @property {Array<{code:string,message:string}>} deprecations - Deprecation-Hinweise (kein harter Fehler)
+ * @property {Array<{code:string,message:string}>} warnings - Warnungen (kein harter Fehler)
+ */
+/**
+ * Trust Boundary: prueft eine MotionSpec gegen Schema-Form, Primitiv-Allow-List,
+ * Parameter-Grenzen und Injection-Regeln. Erzeugt nie eine Teil-Ausgabe.
+ * @param {Object} spec - die zu pruefende MotionSpec
+ * @param {Object} catalog - geladener Primitiv-Katalog (Allow-List)
+ * @returns {ValidationResult}
+ */
 function validateSpec(spec, catalog) {
   const errors = [];
   const errorCodes = [];
   /* push(code, msg) -> errors bekommt "[code] msg", errorCodes den Code. */
   const push = (code, m) => { errors.push("[" + code + "] " + m); errorCodes.push(code); };
+  const warnings = [];
 
   if (typeof spec !== "object" || spec === null || Array.isArray(spec))
-    return { ok: false, errors: ["[MS-SPEC-OBJ] Spec ist kein Objekt."], errorCodes: ["MS-SPEC-OBJ"], deprecations: [] };
+    return { ok: false, errors: ["[MS-SPEC-OBJ] Spec ist kein Objekt."], errorCodes: ["MS-SPEC-OBJ"], deprecations: [], warnings: [] };
 
   const deprecations = deprecationsFor(spec.specVersion);
 
@@ -183,82 +277,30 @@ function validateSpec(spec, catalog) {
   if (SPEC_VERSIONS.indexOf(spec.specVersion) === -1)
     push("MS-SPEC-VER", "specVersion fehlt oder ist unbekannt (erlaubt: " + SPEC_VERSIONS.join(", ") + ").");
 
-  /* ADR-0001 D2: optional catalogVersion pin for reproducibility. If a spec
-   * pins a catalog hash, it MUST match the loaded catalog — fail-closed, so a
-   * spec written against a different catalog cannot silently compile differently. */
-  if (spec.catalogVersion !== undefined) {
-    if (typeof spec.catalogVersion !== "string" || !CATALOG_PIN_RE.test(spec.catalogVersion)) {
-      push("MS-CATALOG-PIN", "catalogVersion muss ein 16-stelliger Hex-Hash sein (oder weglassen).");
-    } else {
-      const actual = catalogVersion(catalog);
-      if (spec.catalogVersion !== actual)
-        push("MS-CATALOG-PIN-MISMATCH", "catalogVersion-Pin (" + spec.catalogVersion + ") passt nicht zum geladenen Katalog (" + actual + "). Spec wurde gegen einen anderen Katalog geschrieben.");
-    }
-  }
+  validateCatalogPin(spec, catalog, push);
+  validateMeta(spec, push);
 
-  if (!spec.meta || typeof spec.meta !== "object") {
-    push("MS-META-MISSING", "meta fehlt.");
-  } else {
-    Object.keys(spec.meta).forEach((k) => {
-      if (META_KEYS.indexOf(k) === -1) push("MS-META-KEY", 'meta: unbekannter Schluessel "' + k + '".');
-    });
-    if (TARGETS.indexOf(spec.meta.target) === -1)
-      push("MS-META-TARGET", "meta.target fehlt oder wird nicht unterstuetzt (erlaubt: " + TARGETS.join(", ") + ").");
-  }
-
-  if (spec.globals !== undefined) {
-    if (typeof spec.globals !== "object" || spec.globals === null || Array.isArray(spec.globals)) {
-      push("MS-GLOBALS-OBJ", "globals muss ein Objekt sein.");
-    } else {
-      Object.keys(spec.globals).forEach((k) => {
-        if (GLOBALS_KEYS.indexOf(k) === -1) push("MS-GLOBALS-KEY", 'globals: unbekannter Schluessel "' + k + '" (erlaubt: ' + GLOBALS_KEYS.join(", ") + ").");
-      });
-    }
-  }
+  validateGlobals(spec, push, warnings);
 
   if (!Array.isArray(spec.motions) || spec.motions.length === 0) {
     push("MS-SPEC-MOTIONS", "motions fehlt oder ist leer.");
-    return { ok: errors.length === 0, errors, errorCodes, deprecations };
+    return { ok: errors.length === 0, errors, errorCodes, deprecations, warnings };
   }
 
   const seen = {};
-  spec.motions.forEach((m, i) => {
-    const at = "motions[" + i + "]";
-    if (typeof m !== "object" || m === null) { push("MS-MOTION-OBJ", at + " ist kein Objekt."); return; }
-
-    Object.keys(m).forEach((k) => {
-      if (MOTION_KEYS.indexOf(k) === -1) push("MS-MOTION-KEY", at + ': unbekannter Schluessel "' + k + '".');
-    });
-
-    if (typeof m.id !== "string" || !ID_RE.test(m.id))
-      push("MS-ID-FORMAT", at + ": id fehlt oder verletzt das Format [A-Za-z0-9_-]{1,64}.");
-    else if (seen[m.id]) push("MS-ID-DUP", at + ': id "' + m.id + '" ist nicht eindeutig.');
-    else seen[m.id] = true;
+  spec.motions.forEach((m, i) => validateMotion(m, i, catalog, push, seen));
 
-    if (!safeSelector(m.target))
-      push("MS-TARGET-UNSAFE", at + ": target fehlt oder ist kein sicherer CSS-Selektor (verboten: Quotes, Backslash, {, }, ;, @, Steuerzeichen; max. 200 Zeichen).");
-
-    /* --- Kern-Schutz: Primitive-Allow-List --- */
-    if (typeof m.primitive !== "string" || !m.primitive) {
-      push("MS-PRIM-MISSING", at + ": primitive fehlt.");
-    } else if (!catalog[m.primitive]) {
-      push("MS-PRIM-UNKNOWN", at + ': primitive "' + m.primitive + '" existiert nicht im Katalog. '
-        + "Erlaubt sind ausschliesslich: " + Object.keys(catalog).sort().join(", ") + ".");
-    } else {
-      const prim = catalog[m.primitive];
-      validateParams(prim, m.params || {}, at, push, false);
-      if (m.trigger !== undefined) validateTrigger(m.trigger, at, push);
-      if (m.responsive !== undefined) {
-        push("MS-RESP-UNSUPPORTED", at + ": responsive wird in dieser specVersion noch nicht unterstuetzt (geplant fuer 0.2). Feld entfernen.");
-      }
-    }
-  });
-
-  return { ok: errors.length === 0, errors, errorCodes, deprecations };
+  return { ok: errors.length === 0, errors, errorCodes, deprecations, warnings };
 }
 
+/* Phase B security: cap spec payload BEFORE any work (MS-INPUT-TOO-LARGE). A
+ * spec is small by nature (a few motions); anything larger is abuse/DoS. 64 KB
+ * is generous. Single source of truth — the MCP layer (register-tools.js)
+ * imports this instead of redefining it, so the cap can never drift. */
+const MAX_SPEC_BYTES = 64 * 1024;
+
 module.exports = {
-  validateSpec, safeSelector, ID_RE, deprecationsFor, unsafeToken,
+  validateSpec, safeSelector, ID_RE, deprecationsFor, unsafeToken, MAX_SPEC_BYTES,
   SPEC_VERSIONS, DEPRECATED_VERSIONS, TARGETS,
   TOP_KEYS, META_KEYS, GLOBALS_KEYS, MOTION_KEYS,
 };

package/src/discover/discover.js

@@ -22,18 +22,10 @@
 const { loadCatalog } = require("../compiler/catalog.js");
 const { compileSpec } = require("../compiler/compile.js");
 
-/* Heuristisches Intent->Primitiv-Mapping (bewusst konservativ; ein echtes
- * Modell kann das spaeter ersetzen — hier geht es nur um Gap-Findung). */
-const RULES = [
-  { re: /(stagger|nacheinander|gestaffelt|one after|cards?|karten|liste)/i, primitive: "staggerReveal", params: { from: { opacity: 0, y: 32 } } },
-  { re: /(z(ä|ae)hl|counter|hochz(ä|ae)hl|count up|nummer|zahl)/i, primitive: "counterUp", params: {} },
-  { re: /(parallax|tiefe|depth|layer|ebene)/i, primitive: "parallaxLayer", params: {} },
-  { re: /(pin|fixier|sticky|festhalten|haften)/i, primitive: "pinnedSection", params: {} },
-  { re: /(marquee|laufband|logo.?band|ticker|endlos)/i, primitive: "marquee", params: {} },
-  { re: /(skalier|scale|zoom|gr(ö|oe)(ß|ss)er werden)/i, primitive: "scaleOnScroll", params: {} },
-  { re: /(hover|maus|cursor|button)/i, primitive: "cssTransition", params: {} },
-  { re: /(reveal|einblend|fade|erscheinen|appear|headline|(ü|ue)berschrift|gleitet|scroll)/i, primitive: "scrollReveal", params: { from: { opacity: 0, y: 48 } } },
-];
+/* Heuristisches Intent->Primitiv-Mapping aus der gemeinsamen Quelle (TASK-025).
+ * Reihenfolge = API: mapIntent liefert den ERSTEN Treffer. discover ignoriert das
+ * mitgelieferte target (es nimmt intent.target); params werden genutzt. */
+const { KEYWORD_MAP: RULES } = require("../compiler/keyword-map.js");
 
 function mapIntent(what) {
   for (const r of RULES) if (r.re.test(what)) return r;

package/src/mcp/register-tools.js

@@ -9,13 +9,12 @@
  * Tool-Logik — eine Quelle der Wahrheit (ADR-0001 Trust Boundary).
  */
 const { z } = require("zod");
-const { validateSpec } = require("../compiler/validate.js");
+const { validateSpec, MAX_SPEC_BYTES } = require("../compiler/validate.js");
 const { compileSpec } = require("../compiler/compile.js");
 const telemetry = require("../router/telemetry.js");
 
-/* Phase B security: cap MCP input size BEFORE any work. A spec is small by
- * nature (a few motions); anything larger is abuse/DoS. 64 KB is generous. */
-const MAX_SPEC_BYTES = 64 * 1024;
+/* Phase B security: cap MCP input size BEFORE any work. MAX_SPEC_BYTES is the
+ * single source in validate.js (MS-INPUT-TOO-LARGE) — imported, never redefined. */
 function oversizeError(spec) {
   let bytes = Infinity;
   try { bytes = Buffer.byteLength(JSON.stringify(spec) || "", "utf8"); } catch { /* circular/garbage */ }
@@ -35,21 +34,8 @@ const AUTHORING_RULES = [
   "6. If no catalog primitive covers the request, do NOT improvise — tell the user which primitive is missing (this is an escalation signal).",
 ].join("\n");
 
-function catalogSummaryOf(catalog) {
-  return Object.keys(catalog).sort().map((name) => {
-    const p = catalog[name];
-    return {
-      name,
-      version: p.version,
-      purpose: p.purpose,
-      engine: p.engine,
-      cost: (p.performance && p.performance.cost) || 0,
-      paramSchema: p.paramSchema || {},
-      triggerDefaults: p.triggerDefaults || {},
-      reducedMotionFallback: p.a11y && p.a11y.reducedMotionFallback,
-    };
-  });
-}
+/* Katalog-Zusammenfassung aus der gemeinsamen Quelle (TASK-026). */
+const { catalogSummary } = require("../compiler/catalog.js");
 
 /* Registriert die vier Tools.  deps.getCatalog()/getCatVer() liefern stets den
  * AKTUELLEN Katalog (stdio kann via SIGHUP neu laden; der Worker liefert den
@@ -72,7 +58,7 @@ function registerMotionspecTools(server, deps) {
         catalogVersion: getCatVer(),
         specVersion: "1.0",
         authoringRules: AUTHORING_RULES,
-        primitives: catalogSummaryOf(getCatalog()),
+        primitives: catalogSummary(getCatalog()),
         exampleSpec: {
           specVersion: "1.0",
           meta: { project: "example", target: "vanilla-gsap", createdWith: "mcp-host" },

package/src/router/clients.js

@@ -46,13 +46,9 @@ function openAICompatClient(opts) {
 
 /* ---------------------------------------------------------------- */
 
-const KEYWORDS = [
-  { re: /(stagger|nacheinander|gestaffelt|one after|cards?|karten)/i, primitive: "staggerReveal", target: ".features .card", params: { from: { opacity: 0, y: 32 } } },
-  { re: /(parallax|tiefe|depth|layers?|ebenen)/i, primitive: "parallaxLayer", target: ".hero .bg", params: { yPercent: -25 } },
-  { re: /(pin|fixier|sticky|fest)/i, primitive: "pinnedSection", target: ".showcase", params: { distance: "+=100%" } },
-  { re: /(hover|button|maus|cursor)/i, primitive: "cssTransition", target: ".cta-button", params: { hoverValue: "translateY(-4px)" } },
-  { re: /(reveal|einblend|fade|erscheinen|appear|headline|ueberschrift|überschrift|scroll)/i, primitive: "scrollReveal", target: ".hero h1", params: { from: { opacity: 0, y: 48 } } },
-];
+/* Keyword-Heuristik aus der gemeinsamen Quelle (TASK-025) — identisch zu
+ * discover.js, damit der Mock denselben Primitiv-Satz kennt wie der Gap-Report. */
+const { KEYWORD_MAP: KEYWORDS } = require("../compiler/keyword-map.js");
 
 function mockClient(opts) {
   const o = opts || {};

package/src/router/prompt.js

@@ -48,17 +48,8 @@ const FEW_SHOT = [
   },
 ];
 
-function catalogSummary(catalog) {
-  return Object.keys(catalog).sort().map((name) => {
-    const p = catalog[name];
-    return {
-      name,
-      purpose: p.purpose,
-      params: p.paramSchema || {},
-      triggerDefaults: p.triggerDefaults || {},
-    };
-  });
-}
+/* Gemeinsame Katalog-Zusammenfassung (TASK-026) — eine Quelle in catalog.js. */
+const { catalogSummary } = require("../compiler/catalog.js");
 
 function buildSystemPrompt(catalog) {
   return [

package/src/router/route.js

@@ -35,10 +35,24 @@ function extractJson(text) {
   catch { return null; }
 }
 
-/*
- * route(request, { client, catalog, target, noCache }) ->
- *   { ok: true,  spec, source: "cache"|"model"|"model-repaired", attempts, ms }
- * | { ok: false, escalate: true, reason, errors?, attempts, ms }
+/**
+ * @typedef {Object} RouteResult
+ * @property {boolean} ok - true wenn eine gueltige Spec erzeugt wurde
+ * @property {Object} [spec] - die validierte MotionSpec, nur wenn ok=true
+ * @property {"cache"|"model"|"model-repaired"} [source] - Herkunft der Spec, nur wenn ok=true
+ * @property {boolean} [escalate] - true wenn kein Primitiv passt oder die Spec ungueltig blieb (ok=false)
+ * @property {string} [reason] - Eskalationsgrund, nur wenn ok=false
+ * @property {string[]} [errors] - Validierungsfehler des letzten Versuchs, falls vorhanden
+ * @property {number} attempts - Anzahl Modell-Versuche (0 bei Cache-Treffer)
+ * @property {number} ms - Dauer in Millisekunden
+ */
+/**
+ * Routet eine natuerlichsprachliche Anfrage ueber Cache -> Modell -> Trust Boundary
+ * (mit genau einem Reparatur-Versuch) zu einer validierten MotionSpec. Jede Anfrage
+ * erzeugt einen Telemetrie-Messpunkt.
+ * @param {string} request - die Anfrage in natuerlicher Sprache
+ * @param {{client: {name: string, complete: Function}, catalog?: Object, target?: string, noCache?: boolean}} opts - client ist Pflicht
+ * @returns {Promise<RouteResult>}
  */
 async function route(request, opts) {
   const o = opts || {};

package/src/router/telemetry.js

@@ -47,20 +47,29 @@ function log(event) {
   const safe = {};
   for (const k of Object.keys(event)) safe[k] = clamp(event[k]);
   safe.ts = new Date().toISOString();
-  activeSink().append(safe);
+  try { activeSink().append(safe); } catch { /* Sink-Fehler nie an Caller propagieren */ }
 }
 
 async function summary() {
   const records = await activeSink().readAll();
   const byOutcome = {};
   const escalations = {};
+  const avgMs = {};
+  const totalAttempts = {};
+  let total = 0;
   for (const e of records) {
-    byOutcome[e.outcome] = (byOutcome[e.outcome] || 0) + 1;
+    /* TASK-020: der AE-Sink liefert pro outcome EINE aggregierte Zeile mit count;
+     * File-/MemorySink liefern Einzel-Records ohne count -> jeweils 1 zaehlen. */
+    const n = e.count || 1;
+    total += n;
+    byOutcome[e.outcome] = (byOutcome[e.outcome] || 0) + n;
+    if (e.avg_ms !== undefined) avgMs[e.outcome] = Math.round(e.avg_ms || 0);
+    totalAttempts[e.outcome] = (totalAttempts[e.outcome] || 0) + (e.attempts || 0);
     /* #17: nur echte Eskalationen zaehlen fuer das Katalog-Wachstums-Signal */
     if (typeof e.outcome === "string" && e.outcome.startsWith("escalate") && NOISE_OUTCOMES.indexOf(e.outcome) === -1)
-      escalations[e.outcome] = (escalations[e.outcome] || 0) + 1;
+      escalations[e.outcome] = (escalations[e.outcome] || 0) + n;
   }
-  return { total: records.length, byOutcome, escalations };
+  return { total, byOutcome, escalations, avgMs, totalAttempts };
 }
 
 module.exports = { log, summary, setSink, getSink, NOISE_OUTCOMES };