@sigloch/se-engine 1.5.0 → 1.6.1

package/dist/metrics.d.ts

@@ -49,6 +49,6 @@ export { projectLayer, weightNodes, ARCH_TYPES, type MetricLayer } from './layer
 export { CLASS_MAP, classOf, classifyAll, classificationStats, type RuleClass, type Classification, type ClassifiedRule, type ClassificationStats, } from './rule-classify.js';
 export { applyRule, markEmptyDelta, type ApplyResult, type DeltaMark } from './rule-apply.js';
 export { suggestEdits, type Suggestion, type SuggestOptions } from './suggest.js';
-export { steerScore, beatsBySteer, STEER_RULES, EPS_AUGMENT, type SteerScore, type SteerCandidate } from './steer.js';
+export { steerScore, steerTerms, beatsBySteer, STEER_RULES, EPS_AUGMENT, type SteerScore, type SteerTerm, type SteerCandidate, } from './steer.js';
 export { fixFor, mentionedElements, FIX_TEMPLATES, mergeCandidates, applyMergeEdit, contractSimilarity, MERGE_OPERATOR_ID, MERGE_SIMILARITY_THRESHOLD, type SuggestedEdit, } from './fix-templates.js';
 export { buildAdjacency, betweenness, maxBetweenness, detectCommunities, modularityOf, modularityQ, redundancyDensity, intraEdgeFraction, components, componentSizes, sourceSinkPaths, type Adjacency, } from './topology.js';

package/dist/metrics.js

@@ -94,6 +94,11 @@ export { CLASS_MAP, classOf, classifyAll, classificationStats, } from './rule-cl
 export { applyRule, markEmptyDelta } from './rule-apply.js';
 export { suggestEdits } from './suggest.js';
 // CR-SM-292: der Ranking-Score. `targetFor` ist mit dem ℝ⁶-Ranking ersatzlos entfallen.
-export { steerScore, beatsBySteer, STEER_RULES, EPS_AUGMENT } from './steer.js';
+// CR-SM-340: `steerTerms`/`SteerTerm` sind hier nachgetragen. CR-SM-337 hat sie gebaut, damit
+// der Host den Steuerungsraum EXPORTIEREN kann, statt die Normierung ein zweites Mal zu
+// schreiben — und genau diese Zeile hat sie nicht durchgereicht. Die Funktion war da, die Tuer
+// nicht; `package.json` kennt nur `"."`, ein Tiefimport ist also versperrt. Gemessen an
+// graphcode: `import { steerTerms } from '@sigloch/se-engine'` warf SyntaxError.
+export { steerScore, steerTerms, beatsBySteer, STEER_RULES, EPS_AUGMENT, } from './steer.js';
 export { fixFor, mentionedElements, FIX_TEMPLATES, mergeCandidates, applyMergeEdit, contractSimilarity, MERGE_OPERATOR_ID, MERGE_SIMILARITY_THRESHOLD, } from './fix-templates.js';
 export { buildAdjacency, betweenness, maxBetweenness, detectCommunities, modularityOf, modularityQ, redundancyDensity, intraEdgeFraction, components, componentSizes, sourceSinkPaths, } from './topology.js';

package/dist/rule-apply.js

@@ -18,7 +18,7 @@
  * Edit; Vorschläge laufen durchs Gate (nie auto-apply).
  */
 import { evaluateAllRules, isValidTrace } from '@sigloch/contracts/se';
-import { classOf, MT_IRRELEVANT_POLICY } from './rule-classify.js';
+import { classOf, classOfViolation, MT_IRRELEVANT_POLICY } from './rule-classify.js';
 /** Deterministic timestamp for synthesized traces (no Date.now — keeps metrics stable). */
 const APPLY_TS = '2026-07-26T00:00:00.000Z';
 /**
@@ -52,19 +52,25 @@ function addTrace(graph, source, target, type) {
  * @returns graph' + whether an edit was applied. Deterministic.
  */
 export function applyRule(rule, graph, knownViolations) {
-    const cls = classOf(rule.id);
     const allViolations = knownViolations ?? evaluateAllRules(graph, MT_IRRELEVANT_POLICY);
-    const violations = allViolations.filter((v) => v.rule_id === rule.id);
-    if (violations.length === 0) {
+    const typeById = new Map(graph.elements.map((e) => [e.id, e.type]));
+    const forRule = allViolations.filter((v) => v.rule_id === rule.id);
+    if (forRule.length === 0) {
         return { graph, applied: false, reason: 'rule does not fire on this graph (empty Δm)' };
     }
-    if (cls.class !== 'Operator') {
+    // CR-SM-334: die Klasse haengt bei R-21 am Ankerknoten des BEFUNDS, nicht nur an der Regel —
+    // ein Befund am Sender-FUNC (Zweig 3, keine gemeinsame Kette) ist kein Operator, auch wenn
+    // die Regel als Ganzes einer ist. Sonst schlaegt der Optimizer einen Test vor, wo die
+    // Modellierung fehlt.
+    const violations = forRule.filter((v) => classOfViolation(rule.id, typeById.get(v.element_id)).class === 'Operator');
+    if (violations.length === 0) {
+        const cls = classOfViolation(rule.id, typeById.get(forRule[0].element_id));
         return { graph, applied: false, reason: `class=${cls.class}: not a transforming operator` };
     }
     // Find a single additive edge that (a) is meta-model valid for the two
     // elements' stored types (isValidTrace) and (b) links two currently-
     // unconnected nodes, so it genuinely moves the topology.
-    const typeById = new Map(graph.elements.map((e) => [e.id, e.type]));
+    // (`typeById` steht seit CR-SM-334 weiter oben — die Klassifikation je Befund braucht es.)
     // CR-SM-266 B: die where-Patterns lesen die Kinds des Zielknotens mit. Ohne sie wuerde
     // `isValidTrace` jede satisfy-Kante ablehnen und der Operator griffe stumm auf einen anderen
     // Kantentyp aus — ein falscher Vorschlag statt keinem.

package/dist/rule-classify.d.ts

@@ -21,6 +21,33 @@ export interface Classification {
 export declare const CLASS_MAP: Record<string, Classification>;
 /** Classify a single rule id (falls back to ambiguous-unknown). */
 export declare function classOf(ruleId: string): Classification;
+/**
+ * CR-SM-334 (ITEM-2026-095) — die Klasse einer Regel, die MEHRERE Fragen stellt, haengt am
+ * ANKERKNOTEN des Befunds, nicht nur an der Regel-ID.
+ *
+ * Bisher einziger Fall: R-21 seit seiner scharfen Fassung (CR-SM-313). Die Regel hat drei
+ * Zweige, und ihre `domain` waechst genau deshalb auf ['FCHAIN','FUNC']:
+ *   1. ein Ende in GAR KEINER Kette -> still, das ist R-30s Aussage
+ *   2. gemeinsame Kette, aber keine geprueft -> Befund an der KETTE (FCHAIN)
+ *   3. beide in Ketten, aber KEINE gemeinsame -> Befund am SENDER (FUNC)
+ *
+ * Zweig 2 ist ein Operator: es fehlt ein Integrationstest, der Fix fuegt TEST + verify hinzu.
+ * Zweig 3 ist etwas anderes, und der Unterschied ist teuer. Dort fehlt kein Test, sondern die
+ * gemeinsame KETTE — zwei Funktionen reichen einander etwas, ohne dass das Modell sagt, in
+ * welchem Ablauf das passiert. Ein Operator, der hier einen Test vorschlaegt, erzeugt
+ * Testarbeit an einer Stelle, an der Modellierungsarbeit fehlt: der Test wuerde eine
+ * Uebergabe belegen, die im Modell gar nicht vorgesehen ist.
+ *
+ * ENTSCHEIDUNG ZUR KLASSE (Kriterium 3 des CR): Zweig 3 ist **Constraint, ambiguous**. Der
+ * Fix waere zwar additiv (compose-Kanten), aber WELCHE Kette die beiden teilen sollen —
+ * die des Senders verlaengern, die des Empfaengers, oder eine neue aufmachen — steht in
+ * keinem Feld; das ist Modellierungsabsicht. Ein Operator daraus waere geraten, nicht
+ * abgeleitet, und wuerde falsche compose-Kanten erzeugen. Praezedenz: IO-02 ("welcher
+ * Produzent welche Konsumenten behaelt, steht in keinem Feld") und die sechs RC-Regeln
+ * (CR-SM-305). `applyRule`/`suggestEdits` verwerfen Nicht-Operatoren — Zweig 3 bleibt damit
+ * Befund und Steuersignal, was er ist.
+ */
+export declare function classOfViolation(ruleId: string, elementType?: string): Classification;
 export interface ClassifiedRule {
     id: string;
     name: string;

package/dist/rule-classify.js

@@ -62,7 +62,11 @@ export const CLASS_MAP = {
     'R-15': { class: 'Operator', rationale: 'add compose trace FCHAIN→FUNC' },
     'R-16': { class: 'Operator', rationale: 'add io trace ACTOR→UC/FLOW' },
     'R-17': { class: 'Operator', rationale: 'add compose trace SYS→child' },
-    'R-21': { class: 'Operator', rationale: 'add integration TEST + verify for FUNC↔FUNC link' },
+    // CR-SM-334 (ITEM-2026-095, zugesagt in CR-SM-313): dieser Eintrag gilt fuer ZWEIG 2 —
+    // Befund an der KETTE, beide Enden teilen eine Kette, nur geprueft ist sie nicht. Zweig 3
+    // (Befund am SENDER-FUNC) verlangt einen anderen Fix und wird in `classOfViolation`
+    // unterschieden; die Klasse allein kann das nicht tragen, denn sie haengt am Ankerknoten.
+    'R-21': { class: 'Operator', rationale: 'chain has no integration TEST — add TEST + verify for the shared chain' },
     'R-22': { class: 'Operator', rationale: 'add allocate trace FUNC→MOD' },
     'R-23': { class: 'Operator', rationale: 'add allocate trace MOD←FUNC' },
     'RD-01': { class: 'Operator', rationale: 'resolve REQ by adding satisfy/decompose trace' },
@@ -159,6 +163,43 @@ const UNKNOWN = { class: 'Constraint', rationale: 'unclassified — not in CLASS
 export function classOf(ruleId) {
     return CLASS_MAP[ruleId] ?? UNKNOWN;
 }
+/**
+ * CR-SM-334 (ITEM-2026-095) — die Klasse einer Regel, die MEHRERE Fragen stellt, haengt am
+ * ANKERKNOTEN des Befunds, nicht nur an der Regel-ID.
+ *
+ * Bisher einziger Fall: R-21 seit seiner scharfen Fassung (CR-SM-313). Die Regel hat drei
+ * Zweige, und ihre `domain` waechst genau deshalb auf ['FCHAIN','FUNC']:
+ *   1. ein Ende in GAR KEINER Kette -> still, das ist R-30s Aussage
+ *   2. gemeinsame Kette, aber keine geprueft -> Befund an der KETTE (FCHAIN)
+ *   3. beide in Ketten, aber KEINE gemeinsame -> Befund am SENDER (FUNC)
+ *
+ * Zweig 2 ist ein Operator: es fehlt ein Integrationstest, der Fix fuegt TEST + verify hinzu.
+ * Zweig 3 ist etwas anderes, und der Unterschied ist teuer. Dort fehlt kein Test, sondern die
+ * gemeinsame KETTE — zwei Funktionen reichen einander etwas, ohne dass das Modell sagt, in
+ * welchem Ablauf das passiert. Ein Operator, der hier einen Test vorschlaegt, erzeugt
+ * Testarbeit an einer Stelle, an der Modellierungsarbeit fehlt: der Test wuerde eine
+ * Uebergabe belegen, die im Modell gar nicht vorgesehen ist.
+ *
+ * ENTSCHEIDUNG ZUR KLASSE (Kriterium 3 des CR): Zweig 3 ist **Constraint, ambiguous**. Der
+ * Fix waere zwar additiv (compose-Kanten), aber WELCHE Kette die beiden teilen sollen —
+ * die des Senders verlaengern, die des Empfaengers, oder eine neue aufmachen — steht in
+ * keinem Feld; das ist Modellierungsabsicht. Ein Operator daraus waere geraten, nicht
+ * abgeleitet, und wuerde falsche compose-Kanten erzeugen. Praezedenz: IO-02 ("welcher
+ * Produzent welche Konsumenten behaelt, steht in keinem Feld") und die sechs RC-Regeln
+ * (CR-SM-305). `applyRule`/`suggestEdits` verwerfen Nicht-Operatoren — Zweig 3 bleibt damit
+ * Befund und Steuersignal, was er ist.
+ */
+export function classOfViolation(ruleId, elementType) {
+    if (ruleId === 'R-21' && elementType === 'FUNC') {
+        return {
+            class: 'Constraint',
+            rationale: 'handover without a shared chain — model the common FCHAIN; which chain the two '
+                + 'functions should share is modelling intent, not derivable, so no operator',
+            ambiguous: true,
+        };
+    }
+    return classOf(ruleId);
+}
 /** Classify the entire live rule catalog (ALL_RULE_DEFS). */
 export function classifyAll() {
     return ALL_RULE_DEFS.map((r) => {

package/dist/steer.d.ts

@@ -80,6 +80,34 @@ export interface SteerScore {
     /** Zahl der Blackboxes, die in die Rechnung eingegangen sind. */
     measured: number;
 }
+/**
+ * CR-SM-337 (ITEM-2026-059): ein TERM je gemessener Blackbox — die Zwischenrechnung, aus der
+ * `worst` und `mean` entstehen.
+ *
+ * Bis hierher gab `steerScore` nur das Ergebnis heraus. Wer die Terme brauchte — der Host, um
+ * den Steuerungsraum zu exportieren, das GVE-Dashboard, um ihn zu zeigen — musste sie selbst
+ * aus dem Regelstrom ableiten, also die Normierung ein zweites Mal schreiben. Eine zweite
+ * Rechnung ist eine zweite Wahrheit; hier ist sie vermeidbar, weil die Zwischenschritte schon
+ * existierten und nur nicht herausgereicht wurden.
+ *
+ * Die Form spiegelt `SteerTerm` in @sigloch/contracts (`se/readiness.ts`) — dort der Vertrag,
+ * hier die Rechnung.
+ */
+export interface SteerTerm {
+    ruleId: string;
+    elementId: string;
+    value: number;
+    threshold: number;
+    /** `max(0, (value − threshold) / threshold)`, dimensionslos. */
+    overshoot: number;
+}
+/**
+ * Die Terme des Steuerungsraums, in kanonischer Befund-Reihenfolge (CR-SM-240). Rein.
+ *
+ * DIE Quelle für alles Weitere: `steerScore` rechnet daraus, der Host exportiert sie
+ * unverändert. Es gibt genau eine Normierung und genau eine Regel-Liste.
+ */
+export declare function steerTerms(violations: readonly RuleViolation[]): SteerTerm[];
 /** Der Chebyshev-Score eines Zustands, aus seinem Regelstrom. Rein. */
 export declare function steerScore(violations: readonly RuleViolation[]): SteerScore;
 /** Ein Kandidat, so weit der Ranker ihn kennen muss. */

package/dist/steer.js

@@ -37,39 +37,56 @@ const NEUTRAL = { worst: 0, worstAt: null, mean: 0, score: 0, measured: 0 };
  * ist nicht „keine Überschreitung". Dieselbe Konvention wie `policy.X = null` und
  * `moduleMetrics.instability = null`.
  */
-function overshootOf(v) {
+function termOf(v) {
     const value = v.context?.value;
     const budget = v.context?.threshold;
     if (typeof value !== 'number' || typeof budget !== 'number' || budget <= 0)
         return null;
-    return Math.max(0, (value - budget) / budget);
+    return {
+        ruleId: v.rule_id,
+        elementId: v.element_id,
+        value,
+        threshold: budget,
+        overshoot: Math.max(0, (value - budget) / budget),
+    };
+}
+/**
+ * Die Terme des Steuerungsraums, in kanonischer Befund-Reihenfolge (CR-SM-240). Rein.
+ *
+ * DIE Quelle für alles Weitere: `steerScore` rechnet daraus, der Host exportiert sie
+ * unverändert. Es gibt genau eine Normierung und genau eine Regel-Liste.
+ */
+export function steerTerms(violations) {
+    const rules = STEER_RULES;
+    const terms = [];
+    for (const v of violations) {
+        if (!rules.includes(v.rule_id))
+            continue;
+        const t = termOf(v);
+        if (t !== null)
+            terms.push(t);
+    }
+    return terms;
 }
 /** Der Chebyshev-Score eines Zustands, aus seinem Regelstrom. Rein. */
 export function steerScore(violations) {
-    const rules = STEER_RULES;
+    const terms = steerTerms(violations);
+    if (terms.length === 0)
+        return NEUTRAL;
     let worst = 0;
     let worstAt = null;
     let sum = 0;
-    let measured = 0;
-    for (const v of violations) {
-        if (!rules.includes(v.rule_id))
-            continue;
-        const d = overshootOf(v);
-        if (d === null)
-            continue;
-        measured += 1;
-        sum += d;
+    for (const t of terms) {
+        sum += t.overshoot;
         // `>` statt `>=`: bei Gleichstand gewinnt der zuerst gesehene, und die Befund-Sequenz ist
         // seit CR-SM-240 kanonisch — damit ist `worstAt` deterministisch.
-        if (d > worst) {
-            worst = d;
-            worstAt = { ruleId: v.rule_id, elementId: v.element_id };
+        if (t.overshoot > worst) {
+            worst = t.overshoot;
+            worstAt = { ruleId: t.ruleId, elementId: t.elementId };
         }
     }
-    if (measured === 0)
-        return NEUTRAL;
-    const mean = sum / measured;
-    return { worst, worstAt, mean, score: worst + EPS_AUGMENT * mean, measured };
+    const mean = sum / terms.length;
+    return { worst, worstAt, mean, score: worst + EPS_AUGMENT * mean, measured: terms.length };
 }
 /**
  * Vergleicht zwei Kandidaten. `< 0` heisst **a ist besser**; direkt sortierbar.

package/dist/suggest.js

@@ -19,7 +19,7 @@ import { evaluateAllRules } from '@sigloch/contracts/se';
 import { metrics, toArray } from './metrics.js';
 import { steerScore, beatsBySteer } from './steer.js';
 import { applyRule } from './rule-apply.js';
-import { classOf, MT_IRRELEVANT_POLICY } from './rule-classify.js';
+import { classOfViolation, MT_IRRELEVANT_POLICY } from './rule-classify.js';
 import { fixFor, mergeCandidates, applyMergeEdit, MERGE_OPERATOR_ID } from './fix-templates.js';
 /**
  * Rankt die feuernden Operator-Regeln danach, wie weit ihr Sonden-Edit den **Chebyshev-Score**
@@ -43,9 +43,14 @@ export function suggestEdits(graph, opts = {}) {
     for (const v of violations)
         if (!firstByRule.has(v.rule_id))
             firstByRule.set(v.rule_id, v);
+    // CR-SM-334: die Klasse haengt bei R-21 am Ankerknoten des Befunds. Ohne den Typ schlaegt
+    // der Vorschlag fuer Zweig 3 (Uebergabe ohne gemeinsame Kette) einen Integrationstest vor,
+    // wo die gemeinsame Kette fehlt — Testarbeit statt Modellierungsarbeit.
+    const typeOfElement = new Map(graph.elements.map((e) => [e.id, e.type]));
+    const classOfFinding = (ruleId, elementId) => classOfViolation(ruleId, typeOfElement.get(elementId));
     const suggestions = [];
     for (const [ruleId, v] of firstByRule) {
-        if (classOf(ruleId).class !== 'Operator')
+        if (classOfFinding(ruleId, v.element_id).class !== 'Operator')
             continue;
         const probe = applyRule({ id: ruleId }, graph, violations);
         if (!probe.applied)
@@ -77,7 +82,7 @@ export function suggestEdits(graph, opts = {}) {
     // ohnehin nicht anwendbar — vor diesem Block fiel der Fund deshalb ganz heraus, mitsamt
     // dem vertragsbauenden Arm des Aktionsraums (CR-GC-430: COHESIVE 5 -> 2 Schritte).
     for (const [ruleId, v] of firstByRule) {
-        if (classOf(ruleId).class === 'Operator')
+        if (classOfFinding(ruleId, v.element_id).class === 'Operator')
             continue;
         const edit = fixFor(v, graph);
         if (!edit || edit.op !== 'add-trace')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/se-engine",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",