motionspec 1.0.0

package/src/mcp/register-tools.js

@@ -0,0 +1,163 @@
+"use strict";
+/*
+ * register-tools — runtime-agnostische Registrierung der MotionSpec-MCP-Tools
+ * (Phase C / C2).  Registriert die vier motion_-Tools auf einem uebergebenen
+ * McpServer.  KEINE stdio-/process-/createRequire-Annahmen: der Aufrufer
+ * injiziert den Katalog-Zustand (getCatalog/getCatVer); Transport, Katalog-
+ * Reload und Logging gehoeren dem jeweiligen Entrypoint (stdio: server.mjs,
+ * Worker: fetch-Handler).  So teilen sich stdio und Worker exakt dieselbe
+ * Tool-Logik — eine Quelle der Wahrheit (ADR-0001 Trust Boundary).
+ */
+const { z } = require("zod");
+const { validateSpec } = 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;
+function oversizeError(spec) {
+  let bytes = Infinity;
+  try { bytes = Buffer.byteLength(JSON.stringify(spec) || "", "utf8"); } catch { /* circular/garbage */ }
+  if (bytes > MAX_SPEC_BYTES) {
+    return { code: "MS-INPUT-TOO-LARGE", message: "spec exceeds " + MAX_SPEC_BYTES + " bytes (" + bytes + "). Reject without processing." };
+  }
+  return null;
+}
+
+const AUTHORING_RULES = [
+  'Write a MotionSpec JSON object (specVersion "1.0").',
+  '1. "primitive" MUST be a catalog name — nothing else exists. Never invent one.',
+  "2. Params only from the primitive's paramSchema; respect min/max. Omit a param to use its default.",
+  '3. "target" is a plain CSS selector without quotes/special characters (e.g. .hero h1, #cta).',
+  '4. "id" matches [A-Za-z0-9_-]{1,64}, descriptive, unique per motion.',
+  '5. meta.target is "vanilla-gsap". Set globals.respectReducedMotion: true.',
+  "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,
+    };
+  });
+}
+
+/* Registriert die vier Tools.  deps.getCatalog()/getCatVer() liefern stets den
+ * AKTUELLEN Katalog (stdio kann via SIGHUP neu laden; der Worker liefert den
+ * gebundelten Katalog statisch). */
+function registerMotionspecTools(server, deps) {
+  const getCatalog = deps.getCatalog;
+  const getCatVer = deps.getCatVer;
+
+  server.registerTool(
+    "motion_catalog",
+    {
+      title: "MotionSpec catalog & authoring rules",
+      description:
+        "Returns the catalog of verified motion primitives (names, purpose, parameter schemas, defaults) plus the authoring rules for writing a MotionSpec. Call this FIRST, then write the spec yourself and pass it to motion_compile.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    async () => {
+      const out = {
+        catalogVersion: getCatVer(),
+        specVersion: "1.0",
+        authoringRules: AUTHORING_RULES,
+        primitives: catalogSummaryOf(getCatalog()),
+        exampleSpec: {
+          specVersion: "1.0",
+          meta: { project: "example", target: "vanilla-gsap", createdWith: "mcp-host" },
+          globals: { respectReducedMotion: true },
+          motions: [
+            {
+              id: "hero-headline",
+              primitive: "scrollReveal",
+              target: ".hero h1",
+              params: { from: { opacity: 0, y: 48 }, duration: 0.8 },
+              trigger: { start: "top 80%", once: true },
+            },
+          ],
+        },
+      };
+      return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }], structuredContent: out };
+    }
+  );
+
+  server.registerTool(
+    "motion_validate",
+    {
+      title: "Validate a MotionSpec (trust boundary)",
+      description:
+        "Checks a MotionSpec against the schema, the primitive allow-list, parameter bounds and injection rules. Fail-closed: returns ok=false with precise errors. Use to pre-check a spec before compiling.",
+      inputSchema: { spec: z.record(z.string(), z.any()).describe("The MotionSpec JSON object") },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    async ({ spec }) => {
+      const catVer = getCatVer();
+      const big = oversizeError(spec);
+      if (big) {
+        const out = { ok: false, errors: ["[" + big.code + "] " + big.message], deprecations: [], catalogVersion: catVer };
+        return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }], structuredContent: out, isError: true };
+      }
+      const v = validateSpec(spec, getCatalog());
+      telemetry.log({ outcome: v.ok ? "mcp-validate-ok" : "mcp-validate-fail", model: "mcp-host", attempts: 1, errors: v.ok ? undefined : v.errors });
+      const out = { ok: v.ok, errors: v.errors || [], deprecations: v.deprecations || [], catalogVersion: catVer };
+      return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }], structuredContent: out };
+    }
+  );
+
+  server.registerTool(
+    "motion_compile",
+    {
+      title: "Compile a MotionSpec to GSAP/CSS",
+      description:
+        "Validates (fail-closed) and deterministically compiles a MotionSpec into production-ready vanilla-GSAP JavaScript and CSS, with enforced prefers-reduced-motion fallbacks and a performance-budget report. Same spec always yields identical code. Returns {ok, js, css, report} or {ok:false, errors}.",
+      inputSchema: {
+        spec: z.record(z.string(), z.any()).describe("The MotionSpec JSON object"),
+        specName: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/).optional().describe("Optional name used in the artifact header"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    async ({ spec, specName }) => {
+      const catVer = getCatVer();
+      const big = oversizeError(spec);
+      if (big) {
+        const out = { ok: false, errors: ["[" + big.code + "] " + big.message], catalogVersion: catVer };
+        return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }], structuredContent: out, isError: true };
+      }
+      const res = compileSpec(spec, getCatalog(), { specName: specName || "mcp-spec" });
+      telemetry.log({ outcome: res.ok ? "mcp-compile-ok" : "mcp-compile-fail", model: "mcp-host", attempts: 1, errors: res.ok ? undefined : res.errors });
+      const out = res.ok
+        ? { ok: true, js: res.js, css: res.css, report: res.report, catalogVersion: catVer }
+        : { ok: false, errors: res.errors, hint: "Fix the listed errors. Call motion_catalog to re-check allowed primitives and parameter bounds.", catalogVersion: catVer };
+      return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }], structuredContent: out, isError: !res.ok };
+    }
+  );
+
+  server.registerTool(
+    "motion_stats",
+    {
+      title: "MotionSpec usage telemetry",
+      description:
+        "Summary of routing/compile telemetry (counts per outcome). Escalation clusters indicate which new primitive the catalog needs next.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    async () => {
+      const s = await telemetry.summary();
+      const out = { total: s.total, byOutcome: s.byOutcome, escalations: s.escalations, note: "escalations = Katalog-Wachstums-Signal (validate/cache-Rauschen ausgeblendet)" };
+      return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }], structuredContent: out };
+    }
+  );
+}
+
+module.exports = { registerMotionspecTools, AUTHORING_RULES, MAX_SPEC_BYTES };

package/src/mcp/server.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/*
+ * motionspec-mcp-server — stdio-Entrypoint fuer den MotionSpec-Werkzeugkasten.
+ *
+ * Architektur: Der Host-LLM (Claude, Cursor, ...) ist hier selbst der Spec-
+ * Autor (Stufe A). Der Server liefert die Leitplanken (Katalog + Regeln) und
+ * erzwingt die Trust Boundary: motion_compile/motion_validate weisen jede
+ * ungueltige Spec fail-closed ab.
+ *
+ * Phase C / C2: Die Tool-Logik liegt in register-tools.js (runtime-agnostisch)
+ * und wird vom Worker-Entrypoint exakt gleich genutzt.  Diese Datei besorgt nur
+ * das, was stdio-/Node-spezifisch ist: Katalog von Platte laden, SIGHUP-Reload,
+ * stdio-Transport.
+ *
+ * Start:  node src/mcp/server.mjs   (stdio)
+ * Claude Code:  claude mcp add motionspec -- node <repo>/src/mcp/server.mjs
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const { loadCatalog, catalogVersion } = require("../compiler/catalog.js");
+const { registerMotionspecTools } = require("./register-tools.js");
+const pkg = require("../../package.json");
+
+/* Audit-Befund #10 (2026-06-12): Katalog ist neu ladbar. SIGHUP laedt die
+ * Primitive neu, ohne den Server-Prozess zu beenden. */
+let catalog = loadCatalog();
+let catVer = catalogVersion(catalog);
+process.on("SIGHUP", () => {
+  try {
+    catalog = loadCatalog();
+    catVer = catalogVersion(catalog);
+    console.error("[motionspec-mcp] Katalog neu geladen — " + catVer + " (" + Object.keys(catalog).length + " primitives)");
+  } catch (e) {
+    console.error("[motionspec-mcp] Katalog-Reload abgelehnt (alter Stand bleibt aktiv): " + e.message);
+  }
+});
+
+const server = new McpServer({ name: "motionspec-mcp-server", version: pkg.version });
+registerMotionspecTools(server, { getCatalog: () => catalog, getCatVer: () => catVer });
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[motionspec-mcp] ready — catalog " + catVer + " (" + Object.keys(catalog).length + " primitives)");

package/src/router/cache.js

@@ -0,0 +1,81 @@
+"use strict";
+/*
+ * Anfrage->Spec-Cache.  Schluessel: sha256(anfrage + katalogVersion + ziel).
+ * Wiederkehrende Anfragen kosten beim zweiten Mal nichts — weder Tokens
+ * noch Wartezeit. Katalog-Aenderung invalidiert automatisch (Versions-Hash).
+ * Ablage: .cache/<key>.json im Repo (gitignored).
+ *
+ * Audit-Befund #11 (2026-06-12): Hygiene. TTL + LRU-Cap + sweep().
+ * Eintraege tragen { spec, savedAt }; abgelaufene/ueberzaehlige werden
+ * entfernt. (Cache-Treffer werden zusaetzlich in route.js re-validiert —
+ * Befund #2 —, daher ist der Cache nie eine Vertrauensgrenze.)
+ */
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const CACHE_DIR = path.join(__dirname, "..", "..", ".cache");
+const TTL_MS = 30 * 24 * 60 * 60 * 1000; /* 30 Tage */
+const MAX_ENTRIES = 500;
+
+function key(request, catalogVer, target) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify({ r: request.trim().toLowerCase(), v: catalogVer, t: target }))
+    .digest("hex")
+    .slice(0, 32);
+}
+
+function get(k) {
+  const f = path.join(CACHE_DIR, k + ".json");
+  if (!fs.existsSync(f)) return null;
+  try {
+    const entry = JSON.parse(fs.readFileSync(f, "utf8"));
+    if (entry && entry.savedAt && Date.now() - entry.savedAt > TTL_MS) {
+      try { fs.unlinkSync(f); } catch { /* ignore */ }
+      return null;
+    }
+    return entry && entry.spec ? entry.spec : entry; /* Rueckwaerts-kompatibel */
+  } catch { return null; }
+}
+
+function set(k, spec) {
+  if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, { recursive: true });
+  fs.writeFileSync(path.join(CACHE_DIR, k + ".json"), JSON.stringify({ spec, savedAt: Date.now() }, null, 2));
+  evict();
+}
+
+/* LRU per mtime: aelteste Eintraege entfernen, bis MAX_ENTRIES erreicht. */
+function evict() {
+  let files;
+  try { files = fs.readdirSync(CACHE_DIR).filter((f) => f.endsWith(".json")); }
+  catch { return; }
+  if (files.length <= MAX_ENTRIES) return;
+  const withTime = files.map((f) => {
+    const full = path.join(CACHE_DIR, f);
+    let t = 0;
+    try { t = fs.statSync(full).mtimeMs; } catch { /* ignore */ }
+    return { full, t };
+  }).sort((a, b) => a.t - b.t);
+  for (const e of withTime.slice(0, withTime.length - MAX_ENTRIES)) {
+    try { fs.unlinkSync(e.full); } catch { /* ignore */ }
+  }
+}
+
+/* Startup-Sweep: abgelaufene Eintraege entfernen. */
+function sweep() {
+  let files;
+  try { files = fs.readdirSync(CACHE_DIR).filter((f) => f.endsWith(".json")); }
+  catch { return 0; }
+  let removed = 0;
+  for (const f of files) {
+    const full = path.join(CACHE_DIR, f);
+    try {
+      const entry = JSON.parse(fs.readFileSync(full, "utf8"));
+      if (entry && entry.savedAt && Date.now() - entry.savedAt > TTL_MS) { fs.unlinkSync(full); removed++; }
+    } catch { /* ignore */ }
+  }
+  return removed;
+}
+
+module.exports = { key, get, set, sweep, evict, CACHE_DIR, TTL_MS, MAX_ENTRIES };

package/src/router/clients.js

@@ -0,0 +1,98 @@
+"use strict";
+/*
+ * Modell-Clients fuer Stufe A.
+ *
+ *   openAICompatClient — jeder OpenAI-kompatible Endpunkt (OpenRouter,
+ *     Anthropic-Gateway, lokales vLLM ...). Konfig via Optionen oder Env:
+ *     MOTION_BASE_URL (default: https://openrouter.ai/api/v1)
+ *     MOTION_MODEL    (default: anthropic/claude-haiku-4.5)
+ *     MOTION_API_KEY  bzw. OPENROUTER_API_KEY
+ *
+ *   mockClient — deterministischer Offline-Client fuer Tests & Demos.
+ *     Simuliert ein kleines Modell per Keyword-Mapping; kann auf Wunsch
+ *     beim ersten Versuch einen typischen Modellfehler machen (fuer
+ *     Repair-Loop-Tests).
+ */
+
+function openAICompatClient(opts) {
+  const o = opts || {};
+  const baseURL = o.baseURL || process.env.MOTION_BASE_URL || "https://openrouter.ai/api/v1";
+  const apiKey = o.apiKey || process.env.MOTION_API_KEY || process.env.OPENROUTER_API_KEY;
+  const model = o.model || process.env.MOTION_MODEL || "anthropic/claude-haiku-4.5";
+  if (!apiKey) throw new Error("Kein API-Key (MOTION_API_KEY / OPENROUTER_API_KEY).");
+
+  return {
+    name: model,
+    async complete(system, user) {
+      const res = await fetch(baseURL.replace(/\/$/, "") + "/chat/completions", {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: "Bearer " + apiKey },
+        body: JSON.stringify({
+          model,
+          temperature: 0,
+          response_format: { type: "json_object" },
+          messages: [
+            { role: "system", content: system },
+            { role: "user", content: user },
+          ],
+        }),
+      });
+      if (!res.ok) throw new Error("Modell-API " + res.status + ": " + (await res.text()).slice(0, 300));
+      const data = await res.json();
+      return (data.choices && data.choices[0] && data.choices[0].message.content) || "";
+    },
+  };
+}
+
+/* ---------------------------------------------------------------- */
+
+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 } } },
+];
+
+function mockClient(opts) {
+  const o = opts || {};
+  let calls = 0;
+  return {
+    name: "mock-small-model",
+    async complete(system, user) {
+      calls++;
+      /* Optional: erster Versuch liefert einen typischen Modellfehler */
+      if (o.failFirst && calls === 1) {
+        return JSON.stringify({
+          specVersion: "1.0",
+          meta: { target: "vanilla-gsap" },
+          motions: [{ id: "bad motion!", primitive: "magicSparkle", target: ".hero" }],
+        });
+      }
+      const request = user.includes("Anfrage:") ? user : user;
+      const motions = [];
+      const used = new Set();
+      for (const k of KEYWORDS) {
+        if (k.re.test(request) && !used.has(k.primitive)) {
+          used.add(k.primitive);
+          motions.push({
+            id: k.primitive.toLowerCase() + "-" + motions.length,
+            primitive: k.primitive,
+            target: k.target,
+            params: k.params,
+          });
+        }
+      }
+      if (motions.length === 0)
+        return JSON.stringify({ escalate: true, reason: "Kein Katalog-Primitiv passt zur Anfrage." });
+      return JSON.stringify({
+        specVersion: "1.0",
+        meta: { project: "request", target: "vanilla-gsap", createdWith: "mock-small-model" },
+        globals: { respectReducedMotion: true },
+        motions,
+      });
+    },
+  };
+}
+
+module.exports = { openAICompatClient, mockClient };

package/src/router/prompt.js

@@ -0,0 +1,99 @@
+"use strict";
+/*
+ * Stufe A — Prompt-Builder
+ * Das kleine Modell bekommt: Aufgabe, Schema-Regeln, Katalog (Namen +
+ * paramSchemas als Leitplanke) und Few-Shot-Beispiele. Es darf NUR JSON
+ * ausgeben. Alles weitere erzwingt die Trust Boundary.
+ */
+
+const FEW_SHOT = [
+  {
+    request: "Die Hero-Überschrift soll beim Scrollen sanft von unten einblenden.",
+    spec: {
+      specVersion: "1.0",
+      meta: { project: "request", target: "vanilla-gsap", createdWith: "router" },
+      globals: { respectReducedMotion: true },
+      motions: [
+        {
+          id: "hero-headline",
+          primitive: "scrollReveal",
+          target: ".hero h1",
+          params: { from: { opacity: 0, y: 48 }, duration: 0.8 },
+          trigger: { start: "top 80%", once: true },
+        },
+      ],
+    },
+  },
+  {
+    request: "Three feature cards should appear one after another, and the section header pins while you scroll through.",
+    spec: {
+      specVersion: "1.0",
+      meta: { project: "request", target: "vanilla-gsap", createdWith: "router" },
+      globals: { respectReducedMotion: true },
+      motions: [
+        {
+          id: "feature-cards",
+          primitive: "staggerReveal",
+          target: ".features .card",
+          params: { from: { opacity: 0, y: 32 }, stagger: 0.12 },
+        },
+        {
+          id: "features-pin",
+          primitive: "pinnedSection",
+          target: ".features",
+          params: { distance: "+=100%" },
+        },
+      ],
+    },
+  },
+];
+
+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 || {},
+    };
+  });
+}
+
+function buildSystemPrompt(catalog) {
+  return [
+    "Du bist ein Uebersetzer von natuerlichsprachlichen Bewegungs-Anfragen in MotionSpec-JSON (specVersion 1.0).",
+    "Du gibst AUSSCHLIESSLICH ein einzelnes JSON-Objekt aus. Kein Markdown, kein Text davor oder danach.",
+    "",
+    "HARTE REGELN:",
+    '1. "primitive" MUSS einer dieser Katalog-Namen sein: ' + Object.keys(catalog).sort().join(", ") + ". Nichts anderes existiert. Erfinde nie ein Primitiv.",
+    "2. Parameter nur aus dem paramSchema des jeweiligen Primitivs; halte min/max ein. Lass Parameter weg, wenn der Default passt.",
+    '3. "target" ist ein einfacher CSS-Selektor ohne Quotes/Sonderzeichen (z.B. .hero h1, #cta, .features .card).',
+    '4. "id" nur [A-Za-z0-9_-], beschreibend, eindeutig.',
+    '5. meta.target ist immer "vanilla-gsap". globals.respectReducedMotion ist immer true.',
+    "6. Wenn die Anfrage etwas verlangt, das KEIN Katalog-Primitiv abdeckt, gib stattdessen aus:",
+    '   {"escalate": true, "reason": "<kurze Begruendung, welches Primitiv fehlt>"}',
+    "",
+    "KATALOG (Leitplanke):",
+    JSON.stringify(catalogSummary(catalog), null, 1),
+    "",
+    "BEISPIELE:",
+    ...FEW_SHOT.map(
+      (ex) => "Anfrage: " + ex.request + "\nAusgabe: " + JSON.stringify(ex.spec)
+    ),
+  ].join("\n");
+}
+
+function buildRepairPrompt(request, badOutput, errors) {
+  return [
+    "Deine vorige Ausgabe fuer die Anfrage hat die Schema-Validierung NICHT bestanden.",
+    "Anfrage: " + request,
+    "Deine Ausgabe war:",
+    badOutput,
+    "Validierungsfehler:",
+    ...errors.map((e) => "- " + e),
+    "Gib jetzt die korrigierte, vollstaendige MotionSpec als einzelnes JSON-Objekt aus. Nur JSON.",
+  ].join("\n");
+}
+
+module.exports = { buildSystemPrompt, buildRepairPrompt, catalogSummary, FEW_SHOT };

package/src/router/route.js

@@ -0,0 +1,108 @@
+"use strict";
+/*
+ * Modell-Routing (Stufe A) — Anfrage zu Spec.  Konzept Kapitel 8.
+ *
+ *   Anfrage -> Cache?
+ *           -> kleines Modell -> JSON extrahieren -> TRUST BOUNDARY
+ *           -> bei Fehler: genau EIN Reparatur-Versuch (Fehler als Kontext)
+ *           -> bei erneutem Fehler oder Selbst-Eskalation des Modells:
+ *              { escalate: true } — Signal fuer +1 / Katalog-Ausbau.
+ *
+ * Jede Anfrage erzeugt einen Telemetrie-Messpunkt (Konzept §3.3).
+ */
+const { loadCatalog, catalogVersion } = require("../compiler/catalog.js");
+const { validateSpec } = require("../compiler/validate.js");
+const { buildSystemPrompt, buildRepairPrompt } = require("./prompt.js");
+const cache = require("./cache.js");
+const telemetry = require("./telemetry.js");
+
+/* Audit #11: Startup-Sweep einmal pro Prozess — abgelaufene Cache-Eintraege
+ * werden beim ersten Routing entfernt (sweep() war zuvor nie aufgerufen). */
+let swept = false;
+function sweepOnce() {
+  if (swept) return;
+  swept = true;
+  try { cache.sweep(); } catch { /* Cache-Hygiene darf Routing nie blockieren */ }
+}
+
+function extractJson(text) {
+  if (typeof text !== "string") return null;
+  const t = text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  const start = t.indexOf("{");
+  const end = t.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+  try { return JSON.parse(t.slice(start, end + 1)); }
+  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 }
+ */
+async function route(request, opts) {
+  const o = opts || {};
+  const t0 = Date.now();
+  const catalog = o.catalog || loadCatalog();
+  const catVer = catalogVersion(catalog);
+  const target = o.target || "vanilla-gsap";
+  const client = o.client;
+  if (!client) throw new Error("route(): opts.client fehlt (mockClient oder openAICompatClient).");
+  sweepOnce();
+
+  /* ---- 1. Cache ---- */
+  const k = cache.key(request, catVer, target);
+  if (!o.noCache) {
+    const hit = cache.get(k);
+    if (hit) {
+      /* Audit-Befund #2 (2026-06-12): Cache-Treffer durchlaufen die Trust
+       * Boundary ERNEUT — fail-closed gilt auch fuer manipulierte/.stale
+       * Cache-Dateien. Ungueltige Treffer werden verworfen. */
+      const vc = validateSpec(hit, catalog);
+      if (vc.ok) {
+        telemetry.log({ outcome: "cache-hit", key: k, model: null, attempts: 0, ms: Date.now() - t0 });
+        return { ok: true, spec: hit, source: "cache", attempts: 0, ms: Date.now() - t0 };
+      }
+      telemetry.log({ outcome: "cache-invalidated", key: k, model: null, attempts: 0, ms: Date.now() - t0 });
+    }
+  }
+
+  /* ---- 2. Kleines Modell ---- */
+  const system = buildSystemPrompt(catalog);
+  let raw, parsed, errors = [];
+
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    const user = attempt === 1 ? "Anfrage: " + request : buildRepairPrompt(request, raw, errors);
+    try { raw = await client.complete(system, user); }
+    catch (e) {
+      /* Audit-Befund #8: Transportfehler sind Eskalation, keine Exception. */
+      telemetry.log({ outcome: "escalate-transport", key: k, model: client.name, attempts: attempt, ms: Date.now() - t0, error: String(e.message).slice(0, 200) });
+      return { ok: false, escalate: true, reason: "Modell-Transportfehler: " + String(e.message).slice(0, 200), attempts: attempt, ms: Date.now() - t0 };
+    }
+    parsed = extractJson(raw);
+
+    if (!parsed) { errors = ["Ausgabe ist kein parsebares JSON."]; continue; }
+
+    /* Selbst-Eskalation des Modells: Anfrage liegt ausserhalb des Katalogs */
+    if (parsed.escalate === true) {
+      telemetry.log({ outcome: "escalate-no-primitive", key: k, model: client.name, attempts: attempt, ms: Date.now() - t0, reason: parsed.reason || null, request: String(request).slice(0, 500) });
+      return { ok: false, escalate: true, reason: parsed.reason || "Kein passendes Primitiv im Katalog.", attempts: attempt, ms: Date.now() - t0 };
+    }
+
+    /* ---- 3. TRUST BOUNDARY ---- */
+    const v = validateSpec(parsed, catalog);
+    if (v.ok) {
+      cache.set(k, parsed);
+      const source = attempt === 1 ? "model" : "model-repaired";
+      telemetry.log({ outcome: source, key: k, model: client.name, attempts: attempt, ms: Date.now() - t0 });
+      return { ok: true, spec: parsed, source, attempts: attempt, ms: Date.now() - t0 };
+    }
+    errors = v.errors;
+  }
+
+  /* ---- 4. Eskalation nach gescheitertem Repair ---- */
+  telemetry.log({ outcome: "escalate-invalid", key: k, model: client.name, attempts: 2, ms: Date.now() - t0, errors, request: String(request).slice(0, 500) });
+  return { ok: false, escalate: true, reason: "Spec auch nach Reparatur-Versuch ungueltig.", errors, attempts: 2, ms: Date.now() - t0 };
+}
+
+module.exports = { route, extractJson };

package/src/router/telemetry-sink.js

@@ -0,0 +1,53 @@
+"use strict";
+/*
+ * Telemetrie-Sink — Speicher-Abstraktion fuer die Telemetrie (Phase C, C1).
+ * Trennt das WIE-gespeichert-wird vom WAS-gemessen-wird: telemetry.js macht
+ * Clamping + Aggregation, der Sink nur I/O.  Dadurch laeuft dieselbe
+ * Telemetrie-Logik lokal (FileSink, JSONL) wie spaeter auf einem Cloudflare
+ * Worker (AnalyticsEngineSink) — eine Quelle, zwei Backends.
+ * Sink-Vertrag:  append(record) -> void ;  readAll() -> record[].
+ */
+const fs = require("fs");
+const path = require("path");
+
+class FileSink {
+  constructor(file) {
+    this.file = file;
+    this._dirReady = false;
+  }
+
+  _ensureDir() {
+    if (this._dirReady) return;
+    const dir = path.dirname(this.file);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    this._dirReady = true;
+  }
+
+  /* Append-only JSONL — ein Record pro Zeile. */
+  append(record) {
+    this._ensureDir();
+    fs.appendFileSync(this.file, JSON.stringify(record) + "\n");
+  }
+
+  /* Alle Records; fehlende Datei -> []; kaputte Zeilen werden uebersprungen. */
+  readAll() {
+    if (!fs.existsSync(this.file)) return [];
+    const lines = fs.readFileSync(this.file, "utf8").trim().split("\n").filter(Boolean);
+    const out = [];
+    for (const l of lines) {
+      try { out.push(JSON.parse(l)); } catch { /* kaputte Zeile ignorieren */ }
+    }
+    return out;
+  }
+}
+
+/* MemorySink — fluechtiger In-Memory-Sink ohne fs (Phase C / C3).  Der Worker
+ * nutzt ihn als Default, damit telemetry.log auf workerd nicht in die (read-only)
+ * fs greift; C4 ersetzt ihn durch den AnalyticsEngineSink (durable). */
+class MemorySink {
+  constructor() { this._records = []; }
+  append(record) { this._records.push(record); }
+  readAll() { return this._records.slice(); }
+}
+
+module.exports = { FileSink, MemorySink };