@sigloch/contracts 6.3.0 → 10.0.0

package/dist/se/rules.js

@@ -5,8 +5,9 @@
  */
 import { z } from 'zod/v4';
 import { ElementType, TraceType, TestRefsSchema, RealRefSchema } from './ontology.js';
-import { isValidTrace } from './meta-model.js';
+import { traceRejection, BOUNDED_PATTERNS, REQUIRED_PATTERNS, maxOccurs } from './meta-model.js';
 import { indexOf } from './graph-index.js';
+import { crossingContractCount, subtreeFuncs } from './module-crossings.js';
 export const RuleSeverity = z.enum(['error', 'warning', 'info']);
 /** Candidate target for resolving a violation (e.g. a REQ to satisfy, a TEST to link). */
 export const ViolationCandidate = z.object({
@@ -25,6 +26,31 @@ export const ViolationContext = z.object({
     })).optional(),
     parent_module: z.string().optional(),
     current_description: z.string().optional(),
+    /**
+     * CR-SM-304: die WEITEREN Elemente, die derselbe Befund betrifft — heute gesetzt von CR-R03,
+     * das einen Befund je Konflikt-MENGE meldet und ihn am kanonisch ersten Ziel verankert. Ohne
+     * dieses Feld verschwanden die uebrigen Ziele lautlos: der Leser erfuhr von genau einem der
+     * Knoten, an denen sich zwei offene CRs begegnen. Ein Befund darf zusammenfassen, aber nichts
+     * unterschlagen.
+     */
+    also_affects: z.array(z.string()).optional(),
+    /**
+     * CR-SM-288: die gemessene Zahl der Regel an diesem Element — und das Budget, gegen das sie
+     * geschwellt wurde. Zusammen ergeben sie die **Verstoßmasse** `d = max(0, value - threshold)`,
+     * die CR-SM-287 lexikographisch rankt. Ohne diese zwei Felder muesste ein Ranker den
+     * Meldungstext parsen; CR-SM-280 hat genau diese Texte umgeschrieben, ohne dass sich ein
+     * Urteil aenderte.
+     *
+     * `threshold` ist der **groesste Wert, der noch INNERHALB des Budgets liegt** — nicht der
+     * Vergleichswert der Regel. Nur so gilt ueber alle Regeln einheitlich `d > 0 <=> warning`,
+     * obwohl die einen bei `>` und die anderen bei `>=` melden (RD-04/MT-01 exklusiv,
+     * BW-02/CR-01/MT-02 inklusiv). Ein `info`-Befund innerhalb des Budgets hat damit `d = 0`.
+     *
+     * Nur die fuenf messenden Regeln setzen sie (RD-04, BW-02, CR-01, MT-01, MT-02); eine Regel
+     * ohne Zahl laesst sie weg, statt eine zu erfinden.
+     */
+    value: z.number().optional(),
+    threshold: z.number().optional(),
 });
 export const RuleViolation = z.object({
     rule_id: z.string(),
@@ -206,36 +232,6 @@ function funcMustSatisfyReq(graph) {
 // ---------------------------------------------------------------------------
 // R-03: ASIL isolation
 // ---------------------------------------------------------------------------
-function asilIsolation(graph) {
-    const idx = indexOf(graph);
-    const violations = [];
-    const modules = idx.elementsOfType('MOD');
-    for (const mod of modules) {
-        const allocated = graph.traces
-            .filter(t => t.target === mod.id && t.type === 'allocate')
-            .map(t => idx.byId.get(t.source))
-            .filter((e) => !!e);
-        const hasD = allocated.some(e => e.asil === 'D');
-        const hasQM = allocated.some(e => e.asil === 'QM');
-        if (hasD && hasQM) {
-            const dFuncs = allocated.filter(e => e.asil === 'D');
-            const qmFuncs = allocated.filter(e => e.asil === 'QM');
-            violations.push({
-                rule_id: 'R-03',
-                severity: 'error',
-                element_id: mod.id,
-                message: `${mod.id} mixes ASIL-D and ASIL-QM functions`,
-                fix_hint: 'Separate ASIL-D functions into isolated module',
-                context: {
-                    element_type: mod.type,
-                    element_name: mod.name,
-                    candidate_targets: toCandidates([...dFuncs, ...qmFuncs]),
-                },
-            });
-        }
-    }
-    return violations;
-}
 // ---------------------------------------------------------------------------
 // R-04: Modulgroesse GEGEN Kreuzungen (nicht „max module size")
 //
@@ -245,6 +241,13 @@ function asilIsolation(graph) {
 // Urteilsschwelle, die sich weder per grep noch aus dem Regelnamen ablesen laesst, ist nicht
 // ueberpruefbar. Jetzt sind es `policy.moduleSize.{coupled,large,crossings}`.
 // `null` → messen, nicht urteilen: die Regel schweigt.
+//
+// CR-SM-276: „Kreuzung" heisst hier dasselbe wie bei CR-01 — ein Vertrag auf dem io-Pfad
+// `FUNC -io-> FLOW -io-> FUNC` UEBER die Modulgrenze (`module-crossings.ts`). Vorher zaehlte
+// die Regel jede io-Kante einer Modul-FUNC „mit einem Endpunkt ausserhalb der FUNC-Menge" —
+// FLOWs liegen nie in dieser Menge, also zaehlte auch jeder modulINTERNE Fluss mit. Das war der
+// io-Grad des Moduls und fuer jedes Modul mit Datenfluss trivial > `crossings`; damit war R-04
+// faktisch wieder „max module size", der Name, den CR-SM-236 gerade verworfen hatte.
 // ---------------------------------------------------------------------------
 function maxModuleSize(graph, policy) {
     const idx = indexOf(graph);
@@ -254,25 +257,24 @@ function maxModuleSize(graph, policy) {
         return violations;
     const modules = idx.elementsOfType('MOD');
     for (const mod of modules) {
-        const allocatedIds = idx.in(mod.id, 'allocate').map(t => t.source);
+        // CR-SM-282: die Groesse ist die des TEILBAUMS, nicht der direkten Allokation. Ein
+        // Eltern-MOD (`MOD -compose-> MOD`) hat keine direkt allozierten FUNCs; `funcCount`
+        // war dort 0 und die Regel schwieg an genau der Whitebox, in die man hineinklickt.
+        // Fuer ein Blatt-MOD ist die Menge zeichengleich mit der bisherigen (nur `FUNC
+        // -allocate-> MOD` existiert als Pattern) — Regressions-Invariante.
+        const allocatedIds = [...subtreeFuncs(graph, mod.id)];
         const allocated = allocatedIds.map(id => idx.byId.get(id)).filter((e) => !!e);
         const funcCount = allocated.length;
         if (funcCount <= steps.coupled)
             continue;
-        // Count crossing flows: io paths from FUNCs in this module to FUNCs in other modules
-        const funcIds = new Set(allocatedIds);
-        // CR-SM-264: nur die io-Kanten, nicht alle Traces je MOD.
-        const crossings = idx.tracesOfType('io').filter(t => {
-            const srcIn = funcIds.has(t.source);
-            const tgtIn = funcIds.has(t.target);
-            return (srcIn && !tgtIn) || (!srcIn && tgtIn);
-        }).length;
+        // Verschiedene Vertraege (SCHEMA) auf io-Pfaden ueber DIESEN Modulrand — CR-SM-276.
+        const crossings = crossingContractCount(graph, mod.id);
         if (funcCount > steps.large && crossings === 0) {
             violations.push({
                 rule_id: 'R-04',
                 severity: 'info',
                 element_id: mod.id,
-                message: `${mod.id} has ${funcCount} functions but 0 crossings (cohesive, just large)`,
+                message: `${mod.id} has ${funcCount} functions but 0 contracts crossing its module boundary (cohesive, just large)`,
                 fix_hint: `Size alone is not the finding: > ${steps.large} functions without crossing flows is cohesive. Split only if crossings appear`,
                 context: { element_type: mod.type, element_name: mod.name, candidate_targets: toCandidates(allocated) },
             });
@@ -282,7 +284,7 @@ function maxModuleSize(graph, policy) {
                 rule_id: 'R-04',
                 severity: 'warning',
                 element_id: mod.id,
-                message: `${mod.id} has ${funcCount} functions and ${crossings} crossing flows (split recommended)`,
+                message: `${mod.id} has ${funcCount} functions and ${crossings} distinct contract(s) crossing its module boundary (split recommended)`,
                 fix_hint: `Split module into smaller units to reduce coupling (> ${steps.large} functions AND crossing flows)`,
                 context: { element_type: mod.type, element_name: mod.name, candidate_targets: toCandidates(allocated) },
             });
@@ -292,7 +294,7 @@ function maxModuleSize(graph, policy) {
                 rule_id: 'R-04',
                 severity: 'warning',
                 element_id: mod.id,
-                message: `${mod.id} has ${funcCount} functions and ${crossings} crossing flows (high coupling)`,
+                message: `${mod.id} has ${funcCount} functions and ${crossings} distinct contract(s) crossing its module boundary (high coupling)`,
                 fix_hint: 'Reduce crossing flows or split module',
                 context: { element_type: mod.type, element_name: mod.name, candidate_targets: toCandidates(allocated) },
             });
@@ -333,8 +335,9 @@ function testMustVerifyReq(graph) {
 // ---------------------------------------------------------------------------
 function traceConsistency(graph) {
     const idx = indexOf(graph);
+    // CR-SM-266 D5: kein `category !== 'audit'`-Filter mehr — das Attribut ist weg, und mit ihm
+    // die Moeglichkeit, eine Kante per Selbstauskunft aus der Referenzintegritaet zu nehmen.
     return graph.traces
-        .filter(t => t.category !== 'audit')
         .filter(t => {
         const sourceExists = idx.byId.has(t.source);
         const targetExists = idx.byId.has(t.target);
@@ -361,7 +364,9 @@ function flowCompleteness(graph) {
     const idx = indexOf(graph);
     const flows = idx.elementsOfType('FLOW');
     // Producers/consumers of a FLOW are FUNCs or ACTORs (io endpoints on the
-    // upstream/downstream side); UC may consume too. Offer both as candidates.
+    // upstream/downstream side). CR-SM-266 D4: UC ist KEIN Konsument mehr — das Pattern
+    // `FLOW -io-> UC` ist entfallen, ein FLOW erreicht einen UC nur noch ueber ein Kettenglied.
+    // Der fix_hint hat den UC vorher noch angeboten und haette in eine R-18-Ablehnung gefuehrt.
     const sources = graph.elements.filter(e => e.type === 'FUNC' || e.type === 'ACTOR'); // Mehrtyp: ein Durchlauf ist hier billiger als vier Index-Listen zu mischen (Reihenfolge!)
     const io = idx.tracesOfType('io');
     const violations = [];
@@ -383,7 +388,7 @@ function flowCompleteness(graph) {
                 severity: 'warning',
                 element_id: f.id,
                 message: `${f.id} has no consumer (outgoing io)`,
-                fix_hint: 'Link a FUNC, ACTOR, or UC as the target via io trace',
+                fix_hint: 'Link a FUNC or ACTOR as the target via io trace',
                 context: ctx,
             });
         }
@@ -407,25 +412,81 @@ const CIRCULAR_TRACE_TYPES = new Set(['compose', 'allocate', 'relation']);
 function noDirectCircular(graph) {
     const idx = indexOf(graph);
     const violations = [];
-    // Direction-independent key: A↔B is ONE cycle, reported once. Keying on the
-    // message (CR-GC-315 predecessor) never collapsed anything — the two
-    // directions render different messages, so every cycle was reported twice.
-    const seen = new Set();
-    for (const t of graph.traces) {
-        if (!CIRCULAR_TRACE_TYPES.has(t.type))
-            continue;
-        if (!idx.out(t.target, t.type).some(other => other.target === t.source))
-            continue;
-        const key = `${t.type}|${[t.source, t.target].sort().join('|')}`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        violations.push({
-            rule_id: 'R-12',
-            severity: 'warning',
-            element_id: t.source,
-            message: `Circular ${t.type} between ${t.source} and ${t.target}`,
-        });
+    // CR-SM-285: ECHTE Zyklenerkennung statt Rueckkanten-Test.
+    //
+    // Bis hierher pruefte die Regel nur, ob eine Kante DIREKT zurueckläuft (A->B und B->A). Ein
+    // Dreierzyklus A->B->C->A ging vollstaendig durch das Gate, mit null Fehlern — bei einem
+    // Regelnamen, der Azyklizitaet verspricht. Das ist die gefaehrlichere Haelfte: ein Absturz
+    // meldet sich, eine Pruefung, die ihren Gegenstand nicht erreicht, BESTAETIGT.
+    //
+    // Warum es zaehlt: jeder Rollup der Familie setzt Azyklizitaet voraus — `chainOf`/`funcChainOf`
+    // in `module-crossings.ts` (CR-SM-282/-283) tragen `seen`-Guards gegen genau diese Endlosschleife,
+    // `moduleMetrics`, die RD-04-Breitenzaehlung und gves Container-Sicht ebenso. Unter einem Zyklus
+    // ist ein Rollup nicht falsch, sondern UNDEFINIERT. Das R-18-Bein aus CR-SM-283 deckt es NICHT:
+    // bei A->B->C->A hat jeder Knoten genau EINEN compose-Elternteil, die Baum-Eigenschaft ist formal
+    // erfuellt und die Struktur trotzdem kein Baum.
+    //
+    // Gemessen ueber neun Familiengraphen: 0 Zyklen jeder Laenge, also 0 -> 0 Befunde. Die Schaerfung
+    // laesst keinen bestehenden Graphen fallen; sie schliesst eine Luecke, bevor sie jemand findet.
+    //
+    // EIN Befund je Zyklus, nicht je Kante (Klasse CR-SM-242): bei einem Ring der Laenge n sind nicht
+    // n Kanten falsch, es ist EINE Struktur. Verankert am kleinsten Knoten des Rings — determiniert,
+    // unabhaengig davon, wo die DFS eingestiegen ist (Gate 5).
+    for (const type of [...CIRCULAR_TRACE_TYPES].sort()) {
+        const adj = new Map();
+        for (const t of graph.traces) {
+            if (t.type !== type)
+                continue;
+            const list = adj.get(t.source);
+            if (list)
+                list.push(t.target);
+            else
+                adj.set(t.source, [t.target]);
+        }
+        for (const list of adj.values())
+            list.sort();
+        const WHITE = 0, GREY = 1, BLACK = 2;
+        const color = new Map();
+        const stack = [];
+        const found = new Map(); // kanonischer Schluessel -> Ring in Reihenfolge
+        const visit = (u) => {
+            color.set(u, GREY);
+            stack.push(u);
+            for (const v of adj.get(u) ?? []) {
+                if (color.get(v) === GREY) {
+                    const ring = stack.slice(stack.indexOf(v));
+                    // Kanonisch: am kleinsten Knoten rotiert, damit derselbe Ring aus jedem Einstieg
+                    // denselben Schluessel und dieselbe Meldung ergibt.
+                    let min = 0;
+                    for (let i = 1; i < ring.length; i++)
+                        if (ring[i] < ring[min])
+                            min = i;
+                    const rotated = [...ring.slice(min), ...ring.slice(0, min)];
+                    found.set(rotated.join('|'), rotated);
+                }
+                else if (color.get(v) === undefined) {
+                    visit(v);
+                }
+            }
+            color.set(u, BLACK);
+            stack.pop();
+        };
+        for (const u of [...adj.keys()].sort())
+            if (color.get(u) === undefined)
+                visit(u);
+        for (const ring of [...found.keys()].sort().map(k => found.get(k))) {
+            const el = idx.byId.get(ring[0]);
+            violations.push({
+                rule_id: 'R-12',
+                severity: 'warning',
+                element_id: ring[0],
+                message: ring.length === 2
+                    ? `Circular ${type} between ${ring[0]} and ${ring[1]}`
+                    : `Circular ${type} over ${ring.length} elements: ${[...ring, ring[0]].join(' -> ')}`,
+                fix_hint: `Break the ${type} ring — every rollup (module boundary, decomposition breadth, container view) is undefined while it exists`,
+                context: { element_type: el?.type, element_name: el?.name },
+            });
+        }
     }
     return violations;
 }
@@ -507,16 +568,46 @@ function noPrematureDecomposition(graph) {
 // RD-04: Decomposition breadth (CR-SM-221)
 // ---------------------------------------------------------------------------
 /**
- * Max children on one decomposition level. The 7–11 convention existed only as
+ * Max children on one decomposition level. The 7±2 convention existed only as
  * prose ("darüber func-of-func"); below 7 is a guideline, not a violation, so only
  * the upper bound is a rule.
  *
  * Counted per (parent, kind) — a MOD that both holds 12 FUNCs and composes 12
  * sub-MODs has two breadth problems, not one. (The spike reference merged both into
  * a single counter on the MOD id and would have reported 24 under one kind.)
+ *
+ * CR-SM-282, zwei Aenderungen:
+ *
+ * 1. **Die Schwelle steht in `policy.decompositionBreadth`**, nicht mehr inline. `null`
+ *    schaltet die Regel ab (messen statt urteilen). Der Default war hier 11 (verhaltensgleich
+ *    zum vorherigen Literal) und ist seit CR-SM-296 **9** — die Obergrenze von 7±2.
+ * 2. **Der FUNC-Wurzelwald zaehlt mit.** Die Regel zaehlt Kinder je *Parent*; die Wurzeln des
+ *    `FUNC -compose-> FUNC`-Waldes haben keinen — die oberste Funktionsebene war damit fuer
+ *    RD-04 unsichtbar. Gemessen: moneyflow hat 306 Wurzel-FUNCs und RD-04 meldete **0**.
+ *    Die MOD-Seite hatte das Problem nie, weil `SYS -compose-> MOD` eine echte Kante ist und
+ *    unten schon als `sub-MOD` gezaehlt wird; die FUNC-Seite hat keine solche Kante
+ *    (`se:top-level`: „the top FUNC set is a PROJECTION, not an edge").
+ *
+ *    Anker ist der SYS-Knoten — determiniert, weil genau einer existiert; gibt es nicht genau
+ *    einen, schweigt dieser Zweig statt zu raten (R-17 deckt den Fall ab). Kein zweiter Weg zur
+ *    Wurzelmenge: es ist dieselbe Definition wie in `se:top-level` (FUNC ohne compose-Elternteil).
  */
-const DECOMPOSITION_BREADTH_MAX = 11;
-function decompositionBreadth(graph) {
+// CR-SM-296: das Bein `FUNC -allocate-> MOD` ist ENTFALLEN und an R-04 abgegeben.
+//
+// Es zaehlte die allozierten FUNCs je Modul — also die MODULGROESSE, und die misst R-04 auch.
+// Beide feuerten am selben Modul im selben Batch, mit zwei Schwellen aus zwei Policy-Feldern:
+//   RD-04  > 11 allozierte FUNC-Kinder        policy.decompositionBreadth
+//   R-04   > 12 FUNCs (bzw. 8-12 mit Kreuzungen)  policy.moduleSize
+// Ein Sachverhalt, zwei Regeln, zwei Zahlen — und welche recht hat, stand nirgends. Schlimmer:
+// dieselbe Ursache ging doppelt in den readiness-Nenner. R-04 ist die reichere Aussage (Groesse
+// GEGEN Kreuzungen, drei Urteile) und liest ueber `moduleCrossings` ohnehin dieselben Daten.
+//
+// RD-04 bleibt fuer ZERLEGUNGSBREITE zustaendig: `FUNC compose FUNC`, `SYS/MOD compose MOD` und
+// der FUNC-Wurzelwald am SYS (CR-SM-282). Je Frage eine Regel, je Frage eine Schwelle.
+function decompositionBreadth(graph, policy) {
+    const max = policy.decompositionBreadth;
+    if (max === null)
+        return [];
     const idx = indexOf(graph);
     // CR-SM-264: `typeOf` und `byId` baute diese Regel je Aufruf selbst — der Index hat beide.
     const typeOf = idx;
@@ -536,48 +627,36 @@ function decompositionBreadth(graph) {
         if (t.type === 'compose' && src === 'FUNC' && tgt === 'FUNC') {
             bump(t.source, 'sub-FUNC');
         }
-        else if (t.type === 'allocate' && tgt === 'MOD' && src === 'FUNC') {
-            bump(t.target, 'allocated FUNC');
-        }
         else if (t.type === 'compose' && (src === 'SYS' || src === 'MOD') && tgt === 'MOD') {
             bump(t.source, 'sub-MOD');
         }
     }
+    // CR-SM-282: der FUNC-Wurzelwald als eigene Blackbox, verankert am SYS-Knoten.
+    const composedFuncs = new Set(graph.traces
+        .filter(t => t.type === 'compose' && typeOf.typeOf(t.source) === 'FUNC' && typeOf.typeOf(t.target) === 'FUNC')
+        .map(t => t.target));
+    const systems = idx.elementsOfType('SYS');
+    if (systems.length === 1) {
+        const rootFuncs = idx.elementsOfType('FUNC').filter(f => !composedFuncs.has(f.id)).length;
+        if (rootFuncs > 0)
+            counts.set(`${systems[0].id}\u0000root FUNC`, { parentId: systems[0].id, kind: 'root FUNC', n: rootFuncs });
+    }
     return [...counts.values()]
-        .filter(c => c.n > DECOMPOSITION_BREADTH_MAX)
+        .filter(c => c.n > max.warning)
         .map(c => {
         const parent = byId.get(c.parentId);
         return {
             rule_id: 'RD-04',
             severity: 'warning',
             element_id: c.parentId,
-            message: `${c.parentId} has ${c.n} ${c.kind} children on one level (>${DECOMPOSITION_BREADTH_MAX})`,
+            message: `${c.parentId} has ${c.n} ${c.kind} children on one level (>${max.warning})`,
             fix_hint: 'Introduce an intermediate level (func-of-func / sub-MOD)',
-            context: { element_type: parent?.type, element_name: parent?.name },
+            // CR-SM-288: `> max.warning` ist exklusiv, also ist `max.warning` selbst noch im Budget.
+            context: { element_type: parent?.type, element_name: parent?.name, value: c.n, threshold: max.warning },
         };
     });
 }
 // ---------------------------------------------------------------------------
-// R-14: UC must have at least 1 compose trace (→ FCHAIN or REQ) (CR-117)
-// ---------------------------------------------------------------------------
-function ucMustHaveCompose(graph) {
-    const idx = indexOf(graph);
-    const ucs = idx.elementsOfType('UC');
-    return ucs
-        .filter(uc => idx.out(uc.id, 'compose').length === 0)
-        .map(uc => ({
-        rule_id: 'R-14',
-        severity: 'warning',
-        element_id: uc.id,
-        message: `${uc.id} has no compose traces (no scenarios or requirements)`,
-        fix_hint: 'Add FCHAIN or REQ via compose trace',
-        context: {
-            element_type: uc.type,
-            element_name: uc.name,
-        },
-    }));
-}
-// ---------------------------------------------------------------------------
 // R-15: FCHAIN completeness — a chain needs functions BELOW it and a use case
 // ABOVE it (CR-117, second leg CR-SM-249).
 //
@@ -660,7 +739,7 @@ function sysMustHaveCompose(graph) {
         severity: 'warning',
         element_id: sys.id,
         message: `${sys.id} has no compose traces (empty system)`,
-        fix_hint: 'Add UC, REQ, or MOD via compose trace',
+        fix_hint: 'Add at least one compose trace — the system decomposes into nothing',
         context: {
             element_type: sys.type,
             element_name: sys.name,
@@ -721,23 +800,192 @@ function validTracePattern(graph) {
     const idx = indexOf(graph);
     // CR-SM-264: die Typ-Map kommt aus dem Index statt je Aufruf neu gebaut zu werden.
     const typeById = { get: (id) => idx.typeOf(id) };
+    // CR-SM-266 D5: der `category !== 'audit'`-Filter ist WEG. Er war die Ausnahme fuer das
+    // einzige audit-Pattern (`SESSION -produces-> *`); mit dessen Entfernung waere er zum
+    // Schlupfloch geworden — eine Kante mit `category: 'audit'` haette die Matrix komplett
+    // umgangen. Das Attribut existiert nicht mehr (ontology.ts), hier faellt der Leser mit.
     return graph.traces
-        .filter(t => t.category !== 'audit')
-        .filter(t => {
+        .flatMap((t) => {
         const src = typeById.get(t.source);
         const tgt = typeById.get(t.target);
         if (!src || !tgt)
-            return false; // dangling endpoint → R-08, not R-18
-        return !isValidTrace({ source: src, target: tgt, type: t.type, label: t.label });
+            return []; // dangling endpoint → R-08, not R-18
+        // CR-SM-266 B: die where-Patterns lesen die Kinds des betroffenen Endes mit.
+        // CR-SM-280: und der GRUND der Ablehnung kommt mit heraus, statt zu `false` zu kollabieren.
+        const why = traceRejection({
+            source: src, target: tgt, type: t.type, label: t.label,
+            sourceKinds: idx.byId.get(t.source)?.kinds,
+            targetKinds: idx.byId.get(t.target)?.kinds,
+        });
+        if (!why)
+            return [];
+        const { detail, hint } = explainRejection(why, t, src, tgt);
+        return [{
+                rule_id: 'R-18',
+                severity: 'error',
+                element_id: t.source,
+                message: `Invalid trace ${t.source} -${t.type}-> ${t.target}: ${detail}`,
+                fix_hint: hint,
+            }];
     })
-        .map(t => ({
-        rule_id: 'R-18',
-        severity: 'error',
-        element_id: t.source,
-        message: `Invalid trace ${t.source} -${t.type}-> ${t.target}: ` +
-            `${typeById.get(t.source)} → ${typeById.get(t.target)} is not a valid ${t.type} pattern`,
-        fix_hint: 'Use a trace type whose TRACE_PATTERNS allows this source/target element-type pair',
-    }));
+        .concat(cardinalityViolations(graph))
+        .concat(singleComposeParent(graph));
+}
+/**
+ * CR-SM-280: aus dem Ablehnungsgrund den Satz bauen, den der Leser braucht.
+ *
+ * Der `no-pattern`-Zweig traegt den Wortlaut von vorher UNVERAENDERT — dort war die alte
+ * Meldung richtig. Nur die beiden `where`-Zweige sind neu, und sie unterscheiden zwei
+ * Ursachen, die vorher zu einer verschmolzen waren: `kinds` fehlt (die BQ-07-Migration) vs.
+ * `kinds` steht da und passt nicht (Kante heben oder Kind korrigieren). Wer das nicht
+ * unterscheiden kann, sucht am falschen Ende.
+ */
+function explainRejection(why, t, src, tgt) {
+    if (why.reason === 'no-pattern') {
+        return {
+            detail: `${src} → ${tgt} is not a valid ${t.type} pattern`,
+            hint: 'Use a trace type whose TRACE_PATTERNS allows this source/target element-type pair',
+        };
+    }
+    const { where } = why.pattern;
+    // Der Knoten wird NUR ueber seine Id benannt, nicht zusaetzlich ueber seinen Typ: der
+    // ElementUid-Kanon (`<TYPE>-<slug>`, ONTOLOGY 8.0.0) traegt den Typ bereits im Namen, und
+    // "REQ REQ-f2-riegel" liest sich wie ein Fehler im Werkzeug.
+    const end = where.on === 'source' ? t.source : t.target;
+    const allowed = [...where.allowed].sort().join(', ');
+    const admits = `the ${src} → ${tgt} ${t.type} pattern admits only ${where.field} {${allowed}}`;
+    return why.reason === 'kinds-undeclared'
+        ? {
+            detail: `${admits}, and ${end} declares no ${where.field}`,
+            hint: `Declare '${where.field}' on ${end} — undeclared is not "any" (CR-SM-266 B); it must be a subset of {${allowed}}`,
+        }
+        : {
+            detail: `${admits}, but ${end} declares {${[...why.declared].sort().join(', ')}}`,
+            hint: `Correct '${where.field}' on ${end}, or use a source type whose ${t.type} pattern admits them (FCHAIN carries every kind)`,
+        };
+}
+/**
+ * CR-SM-283 — das VIERTE BEIN von R-18: die `compose`-Baeume sind Baeume.
+ *
+ * `TRACE_PATTERNS` begrenzt heute nur die KINDER einer Kante, nie die ELTERN
+ * (`se:top-level`: „the cardinalities cap children, not parents"). Ein Element kann damit zwei
+ * `compose`-Elternteile bekommen, und `graph_mutate` legt so eine Kante anstandslos an.
+ *
+ * Warum das hart sein muss, obwohl es NIE vorgekommen ist (0 Verstoesse ueber fuenf
+ * Familiengraphen): jeder Rollup dieser Familie ist unter Verletzung nicht falsch, sondern
+ * UNDEFINIERT — `moduleCrossings.byModule`/`byFunc` (CR-SM-282/-283), die Breiten-Zaehlung von
+ * RD-04, die Container-Sicht von gve. Ein mehrdeutiges Rollup liefert keine schlechtere Zahl,
+ * sondern keine. Das ist der Unterschied zu einer Regel, die „etwas prueft, das nie vorkommt".
+ *
+ * Kein eigener Regel-Eintrag, aus demselben Grund wie beim zweiten und dritten Bein: die
+ * Aussage ist dieselbe — „diese Kante ist nach dem Meta-Modell nicht zulaessig" —, und der
+ * naechste Schritt ist derselbe: eine der beiden Kanten weg.
+ *
+ * EIN Befund je KIND, nicht je ueberzaehliger Kante: bei n Eltern sind nicht n-1 Kanten
+ * „falsch", es ist EINE Entscheidung offen (welcher Elternteil), und n-1 Befunde trieben den
+ * Zaehler ueber den Nenner-Beitrag (die Fehlmessung aus CR-SM-242).
+ */
+function singleComposeParent(graph) {
+    const idx = indexOf(graph);
+    const parents = new Map();
+    for (const t of graph.traces) {
+        if (t.type !== 'compose')
+            continue;
+        const src = idx.typeOf(t.source);
+        const tgt = idx.typeOf(t.target);
+        if (!((src === 'FUNC' && tgt === 'FUNC') || (src === 'MOD' && tgt === 'MOD')))
+            continue;
+        let set = parents.get(t.target);
+        if (!set) {
+            set = new Set();
+            parents.set(t.target, set);
+        }
+        set.add(t.source);
+    }
+    return [...parents.entries()]
+        .filter(([, ps]) => ps.size > 1)
+        // Kanonisch statt in Trace-Reihenfolge — sonst haengt die Befund-Sequenz an der
+        // Eingabereihenfolge (Reihenfolgen-Invariante, se-grammar-invariant.test.ts).
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .map(([child, ps]) => {
+        const el = idx.byId.get(child);
+        const sorted = [...ps].sort();
+        return {
+            rule_id: 'R-18',
+            severity: 'error',
+            element_id: child,
+            message: `${child} has ${sorted.length} compose parents (${sorted.join(', ')}): the compose trees must stay trees`,
+            fix_hint: `Keep exactly one compose parent for ${child} and delete the other edge(s) — every rollup (module boundary, decomposition breadth, container view) is undefined while there are two`,
+            context: { element_type: el?.type, element_name: el?.name },
+        };
+    });
+}
+/**
+ * CR-SM-266b — das ZWEITE BEIN von R-18: die Kardinalitaets-Obergrenzen.
+ * CR-SM-271 Teil 2 — das DRITTE: die durchgesetzten Untergrenzen (heute genau
+ * `FLOW -relation-> SCHEMA [1..1]`; SC-04 ist damit ersatzlos entfallen).
+ *
+ * Bewusst dieselbe `rule_id` und keine eigene, nach dem Muster von R-10 (Produzent/Konsument)
+ * und R-15 seit CR-SM-249: die Aussage ist dieselbe — "diese Kante ist nach dem Meta-Modell
+ * nicht zulaessig" —, nur ist die Bedingung hier eine ueber die MENGE statt ueber das Paar.
+ * Eine eigene ID kostete dauerhaft einen Nenner-Anteil, eine Katalogzeile, eine
+ * readiness-Zuordnung und einen Golden-File-Eintrag (Gate 6), und ein Leser muesste sie von
+ * R-18 unterscheiden, obwohl der naechste Schritt derselbe ist: Kante weg.
+ *
+ * EIN Befund je Quellknoten, nicht je ueberzaehliger Kante. Bei n Allokationen sind nicht
+ * n-1 Kanten "falsch" — es ist EINE Entscheidung offen (welches Modul), und n-1 Befunde
+ * wuerden den Zaehler ueber den Nenner-Beitrag treiben, die Fehlmessung aus CR-SM-242.
+ */
+function cardinalityViolations(graph) {
+    const idx = indexOf(graph);
+    const violations = [];
+    for (const p of BOUNDED_PATTERNS) {
+        const max = maxOccurs(p.cardinality);
+        for (const el of idx.elementsOfType(p.source)) {
+            const matching = idx.out(el.id, p.type).filter(t => idx.typeOf(t.target) === p.target);
+            if (matching.length <= max)
+                continue;
+            violations.push({
+                rule_id: 'R-18',
+                severity: 'error',
+                element_id: el.id,
+                message: `${el.id} has ${matching.length} ${p.type} traces to ${p.target} — ` +
+                    `the meta-model allows at most ${max} (${matching.map(t => t.target).join(', ')})`,
+                fix_hint: `Keep exactly one ${p.type} trace from ${el.id} to a ${p.target} and delete the others`,
+                context: {
+                    element_type: el.type,
+                    element_name: el.name,
+                    existing_traces: matching.map(t => ({ source: t.source, target: t.target, type: t.type })),
+                },
+            });
+        }
+    }
+    // Untergrenzen (CR-SM-271 Teil 2): ein FLOW ohne SCHEMA ist untypisiert, nicht unfertig —
+    // der frueher von SC-04 (warning) gemeldete Fall ist jetzt Grammatik und meldet als error.
+    // EIN Befund je Quellknoten, mit candidate_targets im Kontext (wie SC-04 sie trug), damit
+    // ein Agent die Kante aus dem Payload heraus ergaenzen kann.
+    for (const p of REQUIRED_PATTERNS) {
+        const candidates = idx.elementsOfType(p.target);
+        for (const el of idx.elementsOfType(p.source)) {
+            const matching = idx.out(el.id, p.type).filter(t => idx.typeOf(t.target) === p.target);
+            if (matching.length > 0)
+                continue;
+            violations.push({
+                rule_id: 'R-18',
+                severity: 'error',
+                element_id: el.id,
+                message: `${el.id} has no ${p.type} trace to a ${p.target} — the meta-model requires exactly one`,
+                fix_hint: `Add a ${p.type} trace from ${el.id} to the ${p.target} that defines its contract` +
+                    ` (create the ${p.target} in the same batch if it does not exist yet)`,
+                context: {
+                    element_type: el.type,
+                    element_name: el.name,
+                    candidate_targets: candidates.map(c => ({ id: c.id, type: c.type, name: c.name })),
+                },
+            });
+        }
+    }
+    return violations;
 }
 // ---------------------------------------------------------------------------
 // R-19: Runnable TEST binding (CR-GC-205 Item 4) — a TEST that is not explicitly
@@ -1081,30 +1329,15 @@ function schemaMustHaveSchemaRef(graph) {
 // Symbol is optional on a realRef (a geometry file has none) — presence = a valid
 // realRef with a file. RESOLUTION (file on disk) is a consumer/RC concern.
 // ---------------------------------------------------------------------------
-function physicalModMustHaveRealRef(graph) {
-    const idx = indexOf(graph);
-    return idx.elementsOfType('MOD')
-        .filter(e => e.attributes?.kind === 'physical')
-        .filter(e => e.attributes?.concept !== true && e.attributes?.external !== true)
-        .filter(e => !RealRefSchema.safeParse(e.attributes?.realRef).success)
-        .map(mod => ({
-        rule_id: 'R-27',
-        severity: 'warning',
-        element_id: mod.id,
-        message: `${mod.id} is a physical MOD without a valid realRef (CAD/geometry) binding`,
-        fix_hint: 'Add attributes.realRef {file, symbol?, lang?} pointing at the CAD/geometry artefact, or set attributes.concept:true / attributes.external:true',
-        context: { element_type: mod.type, element_name: mod.name },
-    }));
-}
 // ---------------------------------------------------------------------------
 // R-28 (Ebenen-Präsenz) ist mit CR-SM-247 ersatzlos entfallen — nicht weil sie falsch war,
 // sondern weil sie seit CR-GC-366 doppelt ist. Sie schloss das Vacuous-Complete-Loch (mit 0/1
 // FUNC feuert keine Pro-Element-Regel, alles liest "fertig"); beide Hälften trägt heute je eine
 // präzisere Regel: kein FLOW → R-31 (io-Verdrahtung, je FUNC statt einmal je Graph) + IO-01,
-// kein SCHEMA → SC-04 (je FLOW). Probe (SYS+UC+FCHAIN+3 FUNC, ohne FLOW/SCHEMA): 28 Befunde aus
+// kein SCHEMA → damals SC-04 (je FLOW), seit CR-SM-271 das R-18-Untergrenzen-Bein. Probe
+// (SYS+UC+FCHAIN+3 FUNC, ohne FLOW/SCHEMA): 28 Befunde aus
 // 18 Regeln, ohne R-28 bleiben 17 — das Loch bleibt zu. Gemessen feuerte sie 1× / 0× an den
-// Selbstmodellen, dort neben 14× IO-01 und 10× R-31. Bewusst in Kauf genommen: die
-// SCHEMA-Absenz rutscht von PDR nach CDR, weil SC-04 erst feuert, wenn FLOWs existieren.
+// Selbstmodellen, dort neben 14× IO-01 und 10× R-31.
 // ---------------------------------------------------------------------------
 // ---------------------------------------------------------------------------
 // R-30: jedes BLATT gehoert in eine Wirkkette (CR-GC-366, Grundgesamtheit
@@ -1211,10 +1444,8 @@ export const V3_RULES = [
     { id: 'R-02', name: 'FUNC must satisfy REQ', severity: 'warning', evaluate: funcMustSatisfyReq, domain: ['FUNC'] },
     // CR-SM-243: domain ist MOD, nicht FUNC — die Regel iteriert Module und meldet am Modul,
     // das ASIL-D und QM mischt. Die FUNCs sind der Anlass des Urteils, nicht seine Traeger.
-    { id: 'R-03', name: 'ASIL isolation', severity: 'error', evaluate: asilIsolation, domain: ['MOD'] },
     { id: 'R-04', name: 'Module size relative to crossing flows', severity: 'warning', evaluate: maxModuleSize, domain: ['MOD'] },
     { id: 'R-05', name: 'TEST must verify REQ', severity: 'warning', evaluate: testMustVerifyReq, domain: ['TEST'] },
-    { id: 'R-14', name: 'UC must have compose', severity: 'warning', evaluate: ucMustHaveCompose, domain: ['UC'] },
     { id: 'R-15', name: 'FCHAIN completeness', severity: 'warning', evaluate: fchainCompleteness, domain: ['FCHAIN'] },
     { id: 'R-16', name: 'ACTOR must have io', severity: 'warning', evaluate: actorMustHaveTrace, domain: ['ACTOR'] },
     { id: 'R-17', name: 'SYS must have compose', severity: 'warning', evaluate: sysMustHaveCompose, domain: ['SYS'] },
@@ -1232,7 +1463,6 @@ export const V3_RULES = [
     { id: 'R-22', name: 'FUNC must be allocated to MOD', severity: 'warning', evaluate: funcMustBeAllocated, domain: ['FUNC'] },
     { id: 'R-23', name: 'MOD must have allocated FUNC', severity: 'warning', evaluate: modMustHaveAllocatedFunc, domain: ['MOD'] },
     { id: 'R-26', name: 'SCHEMA must have realRef', severity: 'warning', evaluate: schemaMustHaveSchemaRef, domain: ['SCHEMA'] },
-    { id: 'R-27', name: 'Physical MOD must have realRef', severity: 'warning', evaluate: physicalModMustHaveRealRef, domain: ['MOD'] },
     { id: 'RD-01', name: 'Unresolved requirement', severity: 'warning', evaluate: unresolvedRequirement, domain: ['REQ'] },
     { id: 'RD-02', name: 'Decomposition consistency', severity: 'warning', evaluate: decompositionConsistency, domain: ['REQ'] },
     { id: 'RD-03', name: 'No premature decomposition', severity: 'info', evaluate: noPrematureDecomposition, domain: ['REQ'] },