@sigloch/contracts 10.4.0 → 10.6.0

package/dist/se/metric-rules.js

@@ -1,6 +1,6 @@
 import { decomposedFuncs } from './rules.js';
 import { indexOf } from './graph-index.js';
-import { moduleCrossings } from './module-crossings.js';
+import { moduleCrossings, subtreeFuncs, funcSubtree, boxContracts } from './module-crossings.js';
 /** Geteilte leere Menge — spart je Modul zwei Allokationen in `measureModulesUncached`. */
 const EMPTY_SET = new Set();
 /**
@@ -53,16 +53,13 @@ export function mt02Lcom4(graph, policy) {
         return violations;
     // CR-SM-232: die Union-Find-Rechnung steht in `measureModules`; hier nur die Stufen.
     for (const m of measureModules(graph)) {
+        // CR-SM-326: `null` deckt jetzt beide Faelle, in denen nichts zu urteilen ist — unter zwei
+        // Boxen, und ohne einen einzigen Vertrag im ganzen Modul. Die Ausnahme aus CR-SM-263
+        // (reiner Container-MOD) ist damit erledigt: seit die Box ihren Teilbaum erbt, traegt auch
+        // ein Rollup Vertraege, und die Regel ist dort erfuellbar statt still.
         if (m.lcom4 === null)
             continue;
-        // CR-SM-263: ein MOD aus lauter zerlegten Bloecken ist per Konstruktion zerfallen —
-        // LCOM4 verbindet ueber geteilte io-ZIELE, und CR-SM-256 hat festgehalten, dass
-        // ein Rollup genau die nicht traegt. Die Regel war dort nicht streng, sondern
-        // unerfuellbar: gruen wird sie erst mit der Kante, die CR-SM-256 fuer falsch erklaert.
-        // Die MESSUNG bleibt (`moduleMetrics` liefert `lcom4` unveraendert) — nur das Urteil faellt.
-        if (m.rollupContainer)
-            continue;
-        const message = `${m.moduleName} has LCOM4=${m.lcom4} (${m.allocatedFuncs} FUNCs in ${m.lcom4} disconnected groups)`;
+        const message = `${m.moduleName} has LCOM4=${m.lcom4} (${m.lcom4Boxes} boxes in ${m.lcom4} disconnected groups)`;
         // CR-SM-288: EIN Budget fuer beide Stufen — `steps.warning - 1` ist der groesste LCOM4,
         // der noch drin liegt. Die `info`-Stufe meldet frueher, aber sie meldet keine Ueberschreitung;
         // ihre Masse ist 0.
@@ -76,6 +73,65 @@ export function mt02Lcom4(graph, policy) {
     }
     return violations;
 }
+/**
+ * MT-04: LCOM4 der FUNC-WHITEBOX (CR-SM-327).
+ *
+ * Dasselbe Prinzip wie MT-02, im anderen Baum: die Kinder eines zerlegten FUNC sind die Boxen
+ * seiner Ebene, jede mit den Vertraegen ihres Teilbaums, verbunden ueber den geteilten Vertrag.
+ * BW-02 misst am selben Element den RAND (CR-SM-283) — wie breit die Whitebox nach aussen ist;
+ * hier steht, ob sie innen zusammenhaengt. Zwei Aussagen, zwei Fixes: BW-02 heisst „schneide
+ * die Schnittstelle", MT-04 heisst „das sind zwei Bloecke".
+ *
+ * EIGENE REGEL statt `domain: ['MOD','FUNC']` an MT-02, und das ist keine Geschmacksfrage: die
+ * Grundgesamtheit einer Regel geht in den NENNER ihrer Readiness-Dimension (CR-SM-235/239).
+ * MT-02 liegt in `alloc` (Kern MOD); haengte man FUNC an sie, waechse `alloc.applicable` um
+ * jede FUNC des Graphen — gemessen ueber sieben Familiengraphen steigt der alloc-Score dadurch
+ * um bis zu 0,027 (graphcode 0,932 -> 0,955), ohne dass sich am Graphen etwas verbessert haette.
+ * Genau der Nenner-Defekt der Klasse CR-SM-235/270. Als eigene Regel in `arch` (Kern FUNC) ist
+ * die Bewegung <= 0,008, und die Befunde landen dort, wo FUNC der Gegenstand ist.
+ * Praezedenz fuer den Schnitt: R-20/R-26/R-27 — dieselbe Aussage („braucht einen realRef"),
+ * drei Populationen, drei IDs.
+ *
+ * Die Schwellen sind dieselben (`policy.lcom4`): dieselbe Masszahl, dieselbe Skala. Ein eigenes
+ * Policy-Feld waere eine zweite Schwelle fuer dieselbe Frage.
+ */
+export function mt04WhiteboxLcom4(graph, policy) {
+    const violations = [];
+    const steps = policy.lcom4;
+    if (steps === null)
+        return violations;
+    const idx = indexOf(graph);
+    const decomposed = decomposedFuncs(graph);
+    // In GRAPH-Reihenfolge, nicht in der Reihenfolge der `compose`-Kanten: der Anker eines
+    // Befundes darf nicht an der Kantenreihenfolge haengen (Gate 5).
+    for (const fn of idx.elementsOfType('FUNC')) {
+        if (!decomposed.has(fn.id))
+            continue;
+        const kids = idx.out(fn.id, 'compose')
+            .filter(t => idx.typeOf(t.target) === 'FUNC')
+            .map(t => t.target);
+        const boxes = kids.map(kid => boxContracts(graph, funcSubtree(graph, kid)));
+        const lcom4 = lcom4OfBoxes(boxes);
+        if (lcom4 === null || lcom4 < steps.info)
+            continue;
+        const message = `${fn.name} has LCOM4=${lcom4} (${boxes.length} boxes in ${lcom4} disconnected groups)`;
+        const context = {
+            element_type: fn.type,
+            element_name: fn.name,
+            value: lcom4,
+            threshold: steps.warning - 1,
+        };
+        violations.push({
+            rule_id: 'MT-04',
+            severity: lcom4 >= steps.warning ? 'warning' : 'info',
+            element_id: fn.id,
+            message,
+            fix_hint: 'Split the whitebox along its groups, or wire the groups together where they really share data — a block whose children share no contract is two blocks',
+            context,
+        });
+    }
+    return violations;
+}
 /**
  * CR-SM-221: connection pairs between non-FLOW elements, FLOW-transitive.
  *
@@ -196,6 +252,7 @@ function measureModulesUncached(graph) {
     for (const mod of mods) {
         const allocated = idx.in(mod.id, 'allocate').map(t => t.source);
         const modFuncIds = new Set(allocated);
+        const boxes = boxesOfModule(graph, mod.id, allocated);
         // --- MT-01: fan-in / fan-out als querende VERTRAEGE je Richtung (CR-SM-293) ---
         const fanIn = (crossings.afferentContracts.get(mod.id) ?? EMPTY_SET).size;
         const fanOut = (crossings.efferentContracts.get(mod.id) ?? EMPTY_SET).size;
@@ -207,7 +264,8 @@ function measureModulesUncached(graph) {
             fanIn,
             fanOut,
             instability,
-            lcom4: lcom4Of(graph, allocated),
+            lcom4: lcom4OfBoxes(boxes),
+            lcom4Boxes: boxes.length,
             rollupContainer: allocated.length >= 2 && allocated.every(f => decomposed.has(f)),
             cohesion: cohesionOf(pairs, modFuncIds),
             // CR-SM-301: braucht die Instabilitaet ALLER Module, also zweiter Durchgang unten.
@@ -256,88 +314,82 @@ function measureModulesUncached(graph) {
     }
     return rows;
 }
-/** MT-02 core: connected components over the allocated FUNCs. null below 2 FUNCs. */
-function lcom4Of(graph, funcIds) {
-    if (funcIds.length < 2)
-        return null;
-    // Zwei FUNCs sind verbunden, wenn sie ein gemeinsames `io`-Ziel haben — und NUR dann.
-    //
-    // CR-SM-297: `satisfy` ist aus der Verbindung gefallen. LCOM4 misst Datenkopplung; `satisfy`
-    // ist eine SPEZIFIKATIONS-Beziehung, und zwei FUNCs, die dasselbe REQ erfuellen, koennen zur
-    // Laufzeit vollstaendig entkoppelt sein. Die Wirkung ging dabei nur in eine Richtung:
-    // `satisfy` VERBINDET Gruppen, senkte also LCOM4 und liess Module kohaesiver aussehen, als
-    // ihr Datenfluss hergibt.
-    //
-    // Der Modellierungsgrund wiegt schwerer als der Messgrund: teilen sich zwei Funktionen ein
-    // Requirement, ist das REQUIREMENT zu zerlegen — nicht die Kohaesionsmessung zu beschoenigen.
-    // RD-02 sagt bereits das Verwandte (ein Parent-REQ mit direktem FUNC-satisfy; der satisfy
-    // gehoert an die Kinder).
-    //
-    // CR-SM-264: die ausgehenden Kanten kommen aus dem Index. Vorher lief je alloziertem FUNC
-    // ein Vollscan ueber alle Traces — MOD x FUNC x T.
+/**
+ * CR-SM-326 — die BOXEN einer Modul-Whitebox: ihre Sub-MODs plus ihre direkt allozierten FUNC.
+ *
+ * Die Blackbox-Sicht verlangt genau das: ein zerlegtes Element steht nicht NEBEN seinen Kindern,
+ * es IST sie, von aussen gesehen — und es traegt selbst keine Kante (CR-SM-256). Wer es als
+ * gleichrangigen Nachbarn mit leerer Kantenmenge zaehlt, misst die Zerlegungstiefe statt der
+ * Kohaesion: je besser zerlegt, desto schlechter die Zahl. Dieselbe Besitzkette benutzen R-04
+ * (CR-SM-282), BW-02 (CR-SM-283) und R-23 (CR-SM-321).
+ *
+ * Ein Sub-MOD bringt die FUNCs seines ganzen Modul-Teilbaums mit (`subtreeFuncs`), jede davon
+ * mit ihrem eigenen compose-Teilbaum — sonst fehlten die Blaetter, die gar nicht eigens
+ * alloziert sind.
+ */
+function boxesOfModule(graph, modId, allocated) {
     const idx = indexOf(graph);
-    const funcTargets = new Map();
-    for (const fid of funcIds) {
-        const targets = new Set();
-        for (const t of idx.out(fid, 'io'))
-            targets.add(t.target);
-        funcTargets.set(fid, targets);
+    const boxes = [];
+    for (const t of idx.out(modId, 'compose')) {
+        if (idx.typeOf(t.target) !== 'MOD')
+            continue;
+        const funcs = new Set();
+        for (const f of subtreeFuncs(graph, t.target))
+            for (const x of funcSubtree(graph, f))
+                funcs.add(x);
+        boxes.push(boxContracts(graph, funcs));
     }
-    const parent = new Map();
-    for (const fid of funcIds)
-        parent.set(fid, fid);
-    function find(x) {
-        while (parent.get(x) !== x) {
-            x = parent.get(x);
+    for (const func of allocated)
+        boxes.push(boxContracts(graph, funcSubtree(graph, func)));
+    return boxes;
+}
+/**
+ * MT-02 core: die Zahl der Komponenten ueber den Boxen. Verbunden sind zwei Boxen, wenn sie
+ * einen VERTRAG teilen — dieselbe Zaehlbasis, mit der CR-01, R-04, BW-02 und MT-01 seit
+ * CR-SM-274/276/293 Kopplung zaehlen. Vorher lief die Verbindung ueber FLOW-Identitaet, also
+ * ueber einen zweiten Kopplungsbegriff im selben Katalog.
+ *
+ * CR-SM-297 bleibt in Kraft: `satisfy` verbindet nicht. LCOM4 misst Datenkopplung; teilen sich
+ * zwei Funktionen ein Requirement, gehoert das REQUIREMENT zerlegt.
+ *
+ * `null` heisst messen, nicht urteilen (CR-SM-233) — hier zweimal: unter zwei Boxen gibt es
+ * keine Zerfallenheit, und ohne einen einzigen Vertrag gibt es keine Kopplung, ueber die man
+ * urteilen koennte. Der zweite Fall gehoert R-31 (`FUNC must be wired`), das ihn am Element
+ * meldet; eine Zahl hier waere dieselbe Aussage ein zweites Mal.
+ */
+function lcom4OfBoxes(boxes) {
+    if (boxes.length < 2)
+        return null;
+    if (boxes.every(b => b.size === 0))
+        return null;
+    const parent = boxes.map((_, i) => i);
+    const find = (x) => {
+        let cur = x;
+        while (parent[cur] !== cur) {
+            parent[cur] = parent[parent[cur]];
+            cur = parent[cur];
         }
-        return x;
-    }
-    function union(a, b) {
+        return cur;
+    };
+    const union = (a, b) => {
         const ra = find(a), rb = find(b);
         if (ra !== rb)
-            parent.set(ra, rb);
-    }
-    for (let i = 0; i < funcIds.length; i++) {
-        for (let j = i + 1; j < funcIds.length; j++) {
-            const ti = funcTargets.get(funcIds[i]);
-            const tj = funcTargets.get(funcIds[j]);
-            for (const t of ti) {
-                if (tj.has(t)) {
-                    union(funcIds[i], funcIds[j]);
-                    break;
-                }
-            }
-        }
-    }
-    // CR-165/CR-171: FUNCs sharing the same FLOW (via io in either direction) are connected.
-    const funcIdSet = new Set(funcIds);
-    const flowToFuncs = new Map();
-    for (const t of graph.traces) {
-        if (t.type !== 'io')
-            continue;
-        if (funcIdSet.has(t.target)) {
-            const srcEl = graph.elements.find(e => e.id === t.source);
-            if (srcEl?.type === 'FLOW') {
-                if (!flowToFuncs.has(t.source))
-                    flowToFuncs.set(t.source, new Set());
-                flowToFuncs.get(t.source).add(t.target);
-            }
-        }
-        if (funcIdSet.has(t.source)) {
-            const tgtEl = graph.elements.find(e => e.id === t.target);
-            if (tgtEl?.type === 'FLOW') {
-                if (!flowToFuncs.has(t.target))
-                    flowToFuncs.set(t.target, new Set());
-                flowToFuncs.get(t.target).add(t.source);
-            }
+            parent[ra] = rb;
+    };
+    // Ein Durchgang ueber alle Vertraege statt des Paarvergleichs: der erste Traeger eines
+    // Vertrags zieht jeden weiteren an sich. Linear in der Summe der Boxgroessen — und das
+    // Ergebnis haengt nicht an der Reihenfolge, weil die Komponentenzahl es nicht tut.
+    const firstHolder = new Map();
+    for (let i = 0; i < boxes.length; i++) {
+        for (const contract of boxes[i]) {
+            const first = firstHolder.get(contract);
+            if (first === undefined)
+                firstHolder.set(contract, i);
+            else
+                union(first, i);
         }
     }
-    for (const funcsInFlow of flowToFuncs.values()) {
-        const arr = [...funcsInFlow];
-        for (let i = 1; i < arr.length; i++)
-            union(arr[0], arr[i]);
-    }
-    return new Set(funcIds.map(find)).size;
+    return new Set(boxes.map((_, i) => find(i))).size;
 }
 /** CR-SM-223 core: internal vs. external connection pairs. null where there is no signal. */
 function cohesionOf(pairs, funcIds) {
@@ -400,6 +452,9 @@ export function allocationCohesion(graph) {
 export const MT_RULES = [
     { id: 'MT-01', name: 'Module instability', severity: 'warning', evaluate: mt01Instability, domain: ['MOD'] },
     { id: 'MT-02', name: 'Module cohesion (LCOM4)', severity: 'info', evaluate: mt02Lcom4, domain: ['MOD'] },
+    // CR-SM-327: dieselbe Masszahl an der FUNC-Whitebox. Eigene ID, weil die Grundgesamtheit
+    // die Readiness-Dimension bestimmt (Begruendung an `mt04WhiteboxLcom4`).
+    { id: 'MT-04', name: 'Whitebox cohesion (LCOM4)', severity: 'info', evaluate: mt04WhiteboxLcom4, domain: ['FUNC'] },
     // MT-03 retired as a rule (CR-SM-223) — see `allocationCohesion` above.
 ];
 export function evaluateMTRules(graph, policy) {

package/dist/se/module-crossings.d.ts

@@ -100,3 +100,20 @@ export declare function crossingContractCount(graph: OntologyGraph, modId: strin
 export declare function whiteboxContractCount(graph: OntologyGraph, funcId: string): number;
 /** Die FUNCs im Teilbaum dieses Moduls (direkt alloziert + die seiner Sub-MODs) — CR-SM-282. */
 export declare function subtreeFuncs(graph: OntologyGraph, modId: string): ReadonlySet<string>;
+/**
+ * CR-SM-326: `funcId` plus seine `compose`-Nachfahren im FUNC-Baum — der TEILBAUM, an dessen
+ * Blaettern die io-Kanten liegen (CR-SM-256). Fuer ein Blatt die Einermenge, also derselbe
+ * Aufruf fuer Box und Blatt statt einer Fallunterscheidung beim Aufrufer.
+ */
+export declare function funcSubtree(graph: OntologyGraph, funcId: string): ReadonlySet<string>;
+/**
+ * CR-SM-326: die Vertraege, die eine FUNC-Menge BERUEHRT — dieselbe Zaehlbasis wie
+ * `byModule`/`byFunc` (SCHEMA, sonst `UNBOUND:<flow>`), nur ohne die Rand-Frage.
+ *
+ * Warum ohne Rand: MT-02 fragt nicht, was die Box verlaesst, sondern ob zwei Boxen einen
+ * Vertrag TEILEN. Fuer diese Frage sind Rand- und Beruehrmenge dasselbe — ein Vertrag, den
+ * nur eine Box beruehrt, liegt in keiner zweiten und verbindet niemanden. Die Beruehrmenge
+ * ist die billigere von beiden und braucht die Whitebox-Bedingung aus `byFunc` nicht, die
+ * ein Blatt ausschliesst.
+ */
+export declare function boxContracts(graph: OntologyGraph, funcIds: Iterable<string>): ReadonlySet<string>;

package/dist/se/module-crossings.js

@@ -1,4 +1,16 @@
 import { indexOf } from './graph-index.js';
+/**
+ * Die Vertraege EINES Flusses: seine SCHEMAs, sonst er selbst als untypisierter Vertrag.
+ *
+ * Eine Stelle fuer die Zaehlbasis aus CR-SM-274 — `build()` und `boxContracts()` lesen
+ * dieselbe Funktion, damit es nicht zwei Vorstellungen davon gibt, was ein Vertrag ist.
+ */
+function contractsOfFlow(idx, flowId) {
+    const schemas = idx.out(flowId, 'relation')
+        .filter(t => idx.typeOf(t.target) === 'SCHEMA')
+        .map(t => t.target);
+    return schemas.length > 0 ? schemas : [`UNBOUND:${flowId}`];
+}
 const CACHE = new WeakMap();
 function build(graph) {
     const idx = indexOf(graph);
@@ -85,10 +97,7 @@ function build(graph) {
             .filter(t => idx.typeOf(t.target) === 'FUNC')
             .map(t => modOfFunc.get(t.target))
             .filter((m) => !!m));
-        const schemas = idx.out(flow.id, 'relation')
-            .filter(t => idx.typeOf(t.target) === 'SCHEMA')
-            .map(t => t.target);
-        const contracts = schemas.length > 0 ? schemas : [`UNBOUND:${flow.id}`];
+        const contracts = contractsOfFlow(idx, flow.id);
         // CR-SM-283: derselbe Test auf dem compose-Baum. `allEndpoints` statt `endpoints` —
         // die FUNC-Whitebox kennt keine Modul-Zugehoerigkeit, eine unallozierte FUNC liegt
         // trotzdem drinnen oder draussen.
@@ -194,3 +203,48 @@ export function whiteboxContractCount(graph, funcId) {
 export function subtreeFuncs(graph, modId) {
     return moduleCrossings(graph).funcsByModule.get(modId) ?? new Set();
 }
+/**
+ * CR-SM-326: `funcId` plus seine `compose`-Nachfahren im FUNC-Baum — der TEILBAUM, an dessen
+ * Blaettern die io-Kanten liegen (CR-SM-256). Fuer ein Blatt die Einermenge, also derselbe
+ * Aufruf fuer Box und Blatt statt einer Fallunterscheidung beim Aufrufer.
+ */
+export function funcSubtree(graph, funcId) {
+    const idx = indexOf(graph);
+    const out = new Set();
+    const stack = [funcId];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        if (out.has(cur))
+            continue;
+        out.add(cur);
+        for (const t of idx.out(cur, 'compose')) {
+            if (idx.typeOf(t.target) === 'FUNC')
+                stack.push(t.target);
+        }
+    }
+    return out;
+}
+/**
+ * CR-SM-326: die Vertraege, die eine FUNC-Menge BERUEHRT — dieselbe Zaehlbasis wie
+ * `byModule`/`byFunc` (SCHEMA, sonst `UNBOUND:<flow>`), nur ohne die Rand-Frage.
+ *
+ * Warum ohne Rand: MT-02 fragt nicht, was die Box verlaesst, sondern ob zwei Boxen einen
+ * Vertrag TEILEN. Fuer diese Frage sind Rand- und Beruehrmenge dasselbe — ein Vertrag, den
+ * nur eine Box beruehrt, liegt in keiner zweiten und verbindet niemanden. Die Beruehrmenge
+ * ist die billigere von beiden und braucht die Whitebox-Bedingung aus `byFunc` nicht, die
+ * ein Blatt ausschliesst.
+ */
+export function boxContracts(graph, funcIds) {
+    const idx = indexOf(graph);
+    const out = new Set();
+    for (const func of funcIds) {
+        const flows = [
+            ...idx.out(func, 'io').filter(t => idx.typeOf(t.target) === 'FLOW').map(t => t.target),
+            ...idx.in(func, 'io').filter(t => idx.typeOf(t.source) === 'FLOW').map(t => t.source),
+        ];
+        for (const flow of flows)
+            for (const c of contractsOfFlow(idx, flow))
+                out.add(c);
+    }
+    return out;
+}

package/dist/se/readiness.d.ts

@@ -45,6 +45,51 @@ export type ReadinessScoreType = z.infer<typeof ReadinessScore>;
  * Ein interpretierbarer Ersatz (`1 − Σviolations / Σapplicable`) kommt, wenn er einen
  * Konsumenten hat — nicht auf Vorrat.
  */
+/**
+ * CR-SM-337 (ITEM-2026-059) — der STEUERUNGSRAUM im Bericht, Stufe 1: der Vertrag.
+ *
+ * Readiness misst ABDECKUNG ("wie viele Stellen sind erledigt"), der Steuer-Score AUSPRAEGUNG
+ * ("wie schlimm ist die schlimmste offene"). Beide lesen denselben Regelstrom, und beide
+ * gehoeren in denselben Bericht — sonst rechnet der naechste Leser die zweite Haelfte selbst
+ * nach. Genau das drohte: das GVE-Dashboard (ITEM-2026-018) haette `steerScore` nachbauen
+ * muessen, weil die Zahlen bisher nur als `verdict.steer.improvement` je Suggestion sichtbar
+ * waren. Eine zweite Rechnung ist eine zweite Wahrheit.
+ *
+ * Die Form ist die von `SteerScore` in @sigloch/se-engine (CR-SM-292), ZEICHENGLEICH
+ * uebernommen — contracts darf se-engine nicht importieren (es ist die Basis), also steht hier
+ * der Vertrag und dort die Rechnung. Wer die Form aendert, aendert sie an beiden Stellen; der
+ * Vertragstest daneben haelt die Felder fest.
+ *
+ * `worst` = der schlimmste normierte Ueberschuss `(wert - budget) / budget`. Normiert wird
+ * gegen die REGELSCHWELLE selbst, nicht gegen eine eigene Zahl — deshalb gibt es hier keine
+ * freien Parameter (CR-SM-292: daran ist der Vorgaenger CR-SM-281 gestorben).
+ */
+export declare const SteerTerm: z.ZodObject<{
+    ruleId: z.ZodString;
+    elementId: z.ZodString;
+    value: z.ZodNumber;
+    threshold: z.ZodNumber;
+    overshoot: z.ZodNumber;
+}, z.core.$strip>;
+export type SteerTermType = z.infer<typeof SteerTerm>;
+export declare const SteerSpace: z.ZodObject<{
+    worst: z.ZodNumber;
+    worstAt: z.ZodNullable<z.ZodObject<{
+        ruleId: z.ZodString;
+        elementId: z.ZodString;
+    }, z.core.$strip>>;
+    mean: z.ZodNumber;
+    score: z.ZodNumber;
+    measured: z.ZodNumber;
+    terms: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        elementId: z.ZodString;
+        value: z.ZodNumber;
+        threshold: z.ZodNumber;
+        overshoot: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SteerSpaceType = z.infer<typeof SteerSpace>;
 export declare const ReadinessReport: z.ZodObject<{
     scores: z.ZodArray<z.ZodObject<{
         dimension: z.ZodEnum<{
@@ -63,6 +108,23 @@ export declare const ReadinessReport: z.ZodObject<{
         coreApplicable: z.ZodNumber;
     }, z.core.$strip>>;
     timestamp: z.ZodISODateTime;
+    steer: z.ZodOptional<z.ZodObject<{
+        worst: z.ZodNumber;
+        worstAt: z.ZodNullable<z.ZodObject<{
+            ruleId: z.ZodString;
+            elementId: z.ZodString;
+        }, z.core.$strip>>;
+        mean: z.ZodNumber;
+        score: z.ZodNumber;
+        measured: z.ZodNumber;
+        terms: z.ZodArray<z.ZodObject<{
+            ruleId: z.ZodString;
+            elementId: z.ZodString;
+            value: z.ZodNumber;
+            threshold: z.ZodNumber;
+            overshoot: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ReadinessReportType = z.infer<typeof ReadinessReport>;
 /**

package/dist/se/readiness.js

@@ -57,9 +57,68 @@ export const ReadinessScore = z.object({
  * Ein interpretierbarer Ersatz (`1 − Σviolations / Σapplicable`) kommt, wenn er einen
  * Konsumenten hat — nicht auf Vorrat.
  */
+/**
+ * CR-SM-337 (ITEM-2026-059) — der STEUERUNGSRAUM im Bericht, Stufe 1: der Vertrag.
+ *
+ * Readiness misst ABDECKUNG ("wie viele Stellen sind erledigt"), der Steuer-Score AUSPRAEGUNG
+ * ("wie schlimm ist die schlimmste offene"). Beide lesen denselben Regelstrom, und beide
+ * gehoeren in denselben Bericht — sonst rechnet der naechste Leser die zweite Haelfte selbst
+ * nach. Genau das drohte: das GVE-Dashboard (ITEM-2026-018) haette `steerScore` nachbauen
+ * muessen, weil die Zahlen bisher nur als `verdict.steer.improvement` je Suggestion sichtbar
+ * waren. Eine zweite Rechnung ist eine zweite Wahrheit.
+ *
+ * Die Form ist die von `SteerScore` in @sigloch/se-engine (CR-SM-292), ZEICHENGLEICH
+ * uebernommen — contracts darf se-engine nicht importieren (es ist die Basis), also steht hier
+ * der Vertrag und dort die Rechnung. Wer die Form aendert, aendert sie an beiden Stellen; der
+ * Vertragstest daneben haelt die Felder fest.
+ *
+ * `worst` = der schlimmste normierte Ueberschuss `(wert - budget) / budget`. Normiert wird
+ * gegen die REGELSCHWELLE selbst, nicht gegen eine eigene Zahl — deshalb gibt es hier keine
+ * freien Parameter (CR-SM-292: daran ist der Vorgaenger CR-SM-281 gestorben).
+ */
+export const SteerTerm = z.object({
+    /** Eine der STEER_RULES — die messenden Regeln (se-engine `STEER_RULES`). */
+    ruleId: z.string(),
+    /** Die Blackbox, an der der Term haengt. */
+    elementId: z.string(),
+    /** Der gemessene Wert (`violation.context.value`). */
+    value: z.number(),
+    /** Das Budget, gegen das normiert wird (`violation.context.threshold`). */
+    threshold: z.number(),
+    /** `max(0, (value - threshold) / threshold)` — dimensionslos, damit vergleichbar. */
+    overshoot: z.number().min(0),
+});
+export const SteerSpace = z.object({
+    worst: z.number().min(0),
+    /**
+     * Wo der schlimmste Ueberschuss sitzt — die Begruendung, nicht nur die Zahl.
+     * `null`, wenn nichts ueberschreitet.
+     */
+    worstAt: z.object({ ruleId: z.string(), elementId: z.string() }).nullable(),
+    mean: z.number().min(0),
+    /** `worst + EPS_AUGMENT * mean`. **Kleiner ist besser**, 0 = alles im Budget. */
+    score: z.number().min(0),
+    /**
+     * Zahl der Blackboxes, die in die Rechnung eingegangen sind.
+     *
+     * DIE WICHTIGSTE ZAHL DES OBJEKTS, und zwar wegen `score: 0`: der steht sowohl fuer "alles
+     * innerhalb seiner Budgets" als auch fuer "es wurde nichts gemessen". `measured: 0`
+     * unterscheidet die beiden. Ohne sie waere eine stille Null nicht von einem guten Zustand zu
+     * trennen — dieselbe Konvention wie `policy.X = null` und `moduleMetrics.instability = null`.
+     */
+    measured: z.number().int().min(0),
+    /** Die Terme je Element, aus denen `worst` und `mean` entstehen. */
+    terms: z.array(SteerTerm),
+});
 export const ReadinessReport = z.object({
     scores: z.array(ReadinessScore),
     timestamp: z.iso.datetime(),
+    /**
+     * CR-SM-337: OPTIONAL, damit ein aelterer Produzent gueltig bleibt — der Vertrag wandert vor
+     * dem Fueller (Stufe 2, graphcode CR-GC-537). Fehlt das Feld, heisst das "dieser Produzent
+     * kennt den Steuerungsraum noch nicht", und das ist etwas anderes als `measured: 0`.
+     */
+    steer: SteerSpace.optional(),
 });
 /**
  * CR-SM-305 — welche Profile in die readiness-Zahlen eingehen, und warum `conformance` nicht.
@@ -131,6 +190,10 @@ export const RULE_TO_DIMENSION = {
     // MT-03 is no longer here: it became a measurement (`allocationCohesion`), not a
     // rule (CR-SM-223) — a per-module advisory would depress this score permanently.
     'MT-01': 'alloc', 'MT-02': 'alloc',
+    // CR-SM-327: MT-04 misst die FUNC-Whitebox, nicht das Modul — Grundgesamtheit FUNC,
+    // also `arch` (Kern FUNC). In `alloc` waere sie eine Fremdtyp-Regel und wuerde deren
+    // Nenner um jede FUNC des Graphen aufblaehen (Klasse CR-SM-235/270, gemessen im CR).
+    'MT-04': 'arch',
     // CR traceability
     'CR-R01': 'cr', 'CR-R02': 'cr', 'CR-R03': 'cr', // architecture optimization
     // CR-SM-283: BW-02 (Whitebox-Randbreite) ersetzt AO-D03 an dieser Stelle — dieselbe
@@ -199,7 +262,7 @@ export const RULE_TO_PHASE = {
     // CR-GC-366: Anschluss des Funktionsbaus — gehoert an dasselbe Gate wie R-15/IO-01,
     // die auf derselben Kette aufsetzen.
     'R-30': 'PDR', 'R-31': 'PDR',
-    'MT-01': 'PDR', 'MT-02': 'PDR',
+    'MT-01': 'PDR', 'MT-02': 'PDR', 'MT-04': 'PDR', // CR-SM-327: dieselbe Reifephase wie MT-02
     'ND-01': 'PDR',
     'BW-02': 'PDR', 'CR-01': 'PDR', 'IO-01': 'PDR', 'IO-02': 'PDR', // CR-SM-226: extended to all FCHAIN FUNC-pairs, added to the phase axis.
     // CDR — critical design/schema completeness.

package/dist/se/rule-help.js

@@ -170,7 +170,11 @@ export const RULE_HELP = {
     },
     'MT-02': {
         plain: "The parts inside this module never talk to each other → it is really several modules in one.",
-        se: "LCOM4: the allocated `FUNC`s fall into that many disconnected groups. Connected means shared DATA: a common outgoing `io` target, or touching the same `FLOW` in either direction. CR-SM-297 dropped `satisfy` from that union — two FUNCs meeting the same requirement can be fully decoupled at runtime, and if they share one, the REQUIREMENT is what needs decomposing. `info` from `metricPolicy.lcom4.info`, `warning` from `.warning` (CR-GC-329).",
+        se: "LCOM4 over the BOXES of this module whitebox: its sub-MODs (`MOD -compose-> MOD`) plus its directly allocated `FUNC`s. A box owns its whole subtree, so a decomposed block carries the contracts of its leaves — the same ownership chain R-04 (CR-SM-282), BW-02 (CR-SM-283) and R-23 (CR-SM-321) use; without it a container counted as an empty group of its own and the number grew with decomposition DEPTH (CR-SM-326). Connected means a shared CONTRACT (`FLOW -relation-> SCHEMA`, else the untyped flow) — the same counting base as CR-01/R-04/MT-01 since CR-SM-274/276, not FLOW identity. CR-SM-297 dropped `satisfy`: two FUNCs meeting the same requirement can be fully decoupled at runtime, and if they share one, the REQUIREMENT is what needs decomposing. `null` (no judgement) below two boxes and where no box carries a contract at all — an unwired FUNC is R-31's statement, at the element. `info` from `metricPolicy.lcom4.info`, `warning` from `.warning` (CR-GC-329).",
+    },
+    'MT-04': {
+        plain: "This block's parts never talk to each other → it is really two blocks that happen to sit under one name.",
+        se: "LCOM4 of a decomposed FUNC: its `compose` children are the boxes of that level, each owning its whole subtree, connected when they share a CONTRACT (`FLOW -relation-> SCHEMA`, else the untyped flow) — the same computation MT-02 runs on the module whitebox (CR-SM-326). BW-02 measures the OUTSIDE of the same element (how wide the interface is, CR-SM-283); this one says whether the inside hangs together. `null` (no judgement) below two boxes and where no box carries a contract. Thresholds shared with MT-02 (`metricPolicy.lcom4`) — same measure, same scale.",
     },
     'ND-01': {
         plain: "Two functions look like the same function written twice → merge them, or make clear what each one does differently.",
@@ -294,6 +298,10 @@ export const RULE_HELP = {
         plain: "This element points at code in a package your project does not actually install → either add the package, or point at the one that owns the symbol now.",
         se: "An `external: true` `realRef` names a package that is in neither `dependencies` nor `devDependencies` of the consumer. Absent dependency data is SILENCE, not a violation — the extractor never looked, and treating that as \"declares nothing\" would report every external binding at once (CR-SM-262).",
     },
+    'RC-07': {
+        plain: "A change request is marked done in the model but still open in the folder (or the other way round), or an open change request has no entry in the model → the folder decides; fix the model.",
+        se: "`CR` node whose `status` (closed = done/dropped/rejected) contradicts `docs/cr/open|done/`, or an OPEN CR file with no `CR` node (anchored at the first `SYS`). Nodes without a file are not reported — history. Absent `crFiles` is SILENCE (CR-SM-329).",
+    },
     'RD-01': {
         plain: "A smallest-piece feature has nothing built to fulfil it → add what implements it.",
         se: "Leaf `REQ` (no `compose`→`REQ` children) with no `satisfy` from a `FUNC`/`FCHAIN`/`MOD`/`SYS`.",

package/dist/se/rules.js

@@ -8,7 +8,7 @@ import { ElementType, TraceType, TestRefsSchema, RealRefSchema } from './ontolog
 import { traceRejection, BOUNDED_PATTERNS, REQUIRED_PATTERNS, maxOccurs } from './meta-model.js';
 import { indexOf } from './graph-index.js';
 import { moduleCrossings, subtreeFuncs } from './module-crossings.js';
-import { functionCriticality } from './function-criticality.js';
+import { functionCriticality, chainsByFunc } from './function-criticality.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({
@@ -1260,14 +1260,11 @@ function fchainMustHaveIntegrationTest(graph, policy) {
     }
     if (connections.length === 0)
         return [];
-    // FUNC → set of FCHAINs composing it. LOKALER Index fuer eine andere Frage als die Kennzahl:
-    // "teilen diese beiden EINE Kette" braucht die Mengen, nicht die Zahl (CR-SM-313).
-    const chainsOfFunc = new Map();
-    for (const t of graph.traces) {
-        if (t.type === 'compose' && typeOf.get(t.source) === 'FCHAIN' && isFunc(t.target)) {
-            (chainsOfFunc.get(t.target) ?? chainsOfFunc.set(t.target, new Set()).get(t.target)).add(t.source);
-        }
-    }
+    // FUNC → set of FCHAINs composing it. CR-SM-335: DIESELBE Rechnung, die auch die Kennzahl
+    // speist — vorher stand hier ein zweiter, lokaler Index ueber dieselbe Kantenmenge. "Teilen
+    // diese beiden EINE Kette" braucht die Mengen, die Infrastruktur-Ausnahme die Zahl; beides
+    // kommt jetzt aus `chainsByFunc` (CR-SM-313 hatte den Helfer zugesagt, CR-SM-314 die Zahl).
+    const chainsOf = chainsByFunc(graph);
     // FCHAINs whose satisfy-REQ is verified by a TEST = chains with an integration test.
     const verifiedReqs = new Set(idx.tracesOfType('verify').map(t => t.target));
     const testedChains = new Set();
@@ -1285,8 +1282,8 @@ function fchainMustHaveIntegrationTest(graph, policy) {
     const violations = [];
     const seen = new Set();
     for (const [p, c] of connections) {
-        const pChains = chainsOfFunc.get(p) ?? new Set();
-        const cChains = chainsOfFunc.get(c) ?? new Set();
+        const pChains = chainsOf.get(p) ?? new Set();
+        const cChains = chainsOf.get(c) ?? new Set();
         // ZWEIG 1 — ein Ende in GAR KEINER Kette: still. Das ist R-30s Aussage, nicht R-21s.
         // Ohne diese Klausel feuert die Regel an einem code-importierten Graphen wie moneyflow
         // 219 von 219 Mal und meldet in Wahrheit "dieses Repo hat keine Wirkketten", einmal je Kante.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/contracts",
-  "version": "10.4.0",
+  "version": "10.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",