@sigloch/contracts 6.3.0 → 10.0.0

package/dist/se/schema-quality-rules.d.ts

@@ -16,6 +16,5 @@ import type { OntologyGraph } from './ontology.js';
 import type { RuleDefinition, RuleViolation } from './rules.js';
 import type { MetricPolicy } from './policy.js';
 export declare function sc02IsReferenced(graph: OntologyGraph): RuleViolation[];
-export declare function sc04FlowHasSchema(graph: OntologyGraph): RuleViolation[];
 export declare const SC_RULES: RuleDefinition[];
 export declare function evaluateSCRules(graph: OntologyGraph, policy: MetricPolicy): RuleViolation[];

package/dist/se/schema-quality-rules.js

@@ -20,40 +20,19 @@ export function sc02IsReferenced(graph) {
     }));
 }
 // ---------------------------------------------------------------------------
-// SC-04: FLOW must reference a SCHEMA (CR-SM-226) — the sharp per-FLOW
-// inverse of SC-02. SC-02 catches an orphan SCHEMA (nobody uses it); SC-04
-// catches a FLOW with no data contract at all — until now only caught
-// loosely, around the SC-02-adjacent CDR completeness leg, never as its own
-// rule.
+// SC-04 (FLOW must reference a SCHEMA, CR-SM-226) ist mit CR-SM-271 Teil 2 ersatzlos
+// entfallen: die Untergrenze ist Grammatik geworden (`FLOW -relation-> SCHEMA [1..1]`,
+// meta-model.ts REQUIRED_PATTERNS) und meldet als error aus dem R-18-Kardinalitaets-Bein
+// (rules.ts cardinalityViolations) — Grammatik ersetzt Regel, kein Regel-Loch.
 // ---------------------------------------------------------------------------
-export function sc04FlowHasSchema(graph) {
-    const schemas = graph.elements.filter(e => e.type === 'SCHEMA');
-    return graph.elements
-        .filter(e => e.type === 'FLOW')
-        .filter(f => !graph.traces.some(t => t.source === f.id && t.type === 'relation' &&
-        graph.elements.some(e => e.id === t.target && e.type === 'SCHEMA')))
-        .map(f => ({
-        rule_id: 'SC-04',
-        severity: 'warning',
-        element_id: f.id,
-        message: `${f.id} has no SCHEMA binding`,
-        fix_hint: 'Link a SCHEMA via relation trace to define this FLOW\'s data contract',
-        context: {
-            element_type: f.type,
-            element_name: f.name,
-            candidate_targets: schemas.map(s => ({ id: s.id, type: s.type, name: s.name })),
-        },
-    }));
-}
 // ---------------------------------------------------------------------------
 // Aggregated array & convenience runner
 // ---------------------------------------------------------------------------
 export const SC_RULES = [
-    // Die Asymmetrie ist gewollt (CR-SM-242): SC-02 iteriert ueber SCHEMA („wird dieses SCHEMA
-    // benutzt"), SC-04 ueber FLOW („hat dieser FLOW einen Datenvertrag"). Gleiches Thema,
-    // verschiedene Grundgesamtheit. SC-04 als ['SCHEMA'] zog 46 FLOW-Verstoesse gegen 20 SCHEMA.
+    // Die Asymmetrie zur FLOW-Seite ist gewollt (CR-SM-242): SC-02 iteriert ueber SCHEMA
+    // („wird dieses SCHEMA benutzt"); die Gegenrichtung je FLOW („hat dieser FLOW einen
+    // Datenvertrag") traegt seit CR-SM-271 das R-18-Untergrenzen-Bein.
     { id: 'SC-02', name: 'Schema referenced by FLOW', severity: 'warning', evaluate: sc02IsReferenced, domain: ['SCHEMA'] },
-    { id: 'SC-04', name: 'FLOW has SCHEMA binding', severity: 'warning', evaluate: sc04FlowHasSchema, domain: ['FLOW'] },
 ];
 // CR-SM-236: `policy` wird durchgereicht, auch wo diese Familie heute keine Schwelle hat —
 // ein Sonderweg je Familie waere genau der zweite Pfad, den der Regelsatz verbietet.

package/dist/se/similarity.d.ts

@@ -0,0 +1,61 @@
+/**
+ * CR-SM-286 — die Ähnlichkeitsrechnung von ND-01/ND-02/BQ-04, dort wo die Regeln stehen.
+ *
+ * ## Warum sie hierher gehört
+ *
+ * Bis hierher lebte die Formel als **Prosa** in `near-duplicate-rules.ts` und als **Code** in
+ * `graphcode/src/kernel/measure/nd-similarity.ts`, verbunden durch
+ * `setND01SimilarityMatrix()` / `setND02SimilarityMatrix()`. Zwei Pakete mussten sich über
+ * etwas einig sein, das nur eines von beiden ausführt.
+ *
+ * Die Naht kostete vier Dinge, alle gemessen:
+ *
+ * 1. **Fail-open.** Ohne Injektion gaben ND-01/ND-02 `[]` zurück — bei severity `error` und
+ *    ununterscheidbar von „keine Duplikate". Gemessen: moneyflow trägt 16 ND-01-Befunde, die
+ *    für JEDEN Konsumenten ausserhalb graphcodes unsichtbar waren (`report:silence`, die
+ *    Spike-Skripte, jedes künftige Werkzeug). Die Familie hat für „kann nicht urteilen" eine
+ *    Konvention — `policy.X = null`, `moduleMetrics.instability = null`, beide sagen es
+ *    ausdrücklich; ND fiel statt dessen nach grün.
+ * 2. **Prozessweiter Modulzustand.** `let _nd01Matrix` ist global. graphcode schützte sich mit
+ *    der Klammer `withNDMatrices(og, run)` und einem `finally`-Reset; jeder andere Aufrufer
+ *    nicht. Zwei Graphen nacheinander bewertet — und Graph A urteilt über Graph B.
+ * 3. **AO-D01 verstärkte es.** Die Regel liegt IM Gate-Katalog und übersprang ihre
+ *    Overlap-Prüfung, wenn keine Matrix da war („no matrix → assume pass"): eine Gate-Regel,
+ *    die sich stillschweigend abschwächt.
+ * 4. **BQ-04 ist am selben Muster komplett tot** — `setBQ04SimilarityMatrix()` ruft im ganzen
+ *    Familienbaum niemand (CR-SM-278, heute erneut geprüft).
+ *
+ * Präzedenz aus demselben Repo: CR-SM-276 hat `moduleCrossings` genau deshalb NACH contracts
+ * gelegt — damit zwei Regelköpfe (CR-01, R-04) EINE Definition von „Kreuzung" teilen. Hier ist
+ * es dieselbe Bewegung für drei Regelköpfe und eine Definition von „ähnlich".
+ *
+ * ## Was sich NICHT ändert
+ *
+ * Formeln, Gewichte und die Schwelle 0,85 sind zeichengleich aus graphcodes Implementierung
+ * übernommen. Das ist kein neues Urteil, es ist derselbe Code an der richtigen Stelle.
+ *
+ * Rein und deterministisch: kein Store, kein Transport, kein Filesystem, kein Zufall, keine
+ * Abhängigkeit ausserhalb der Ontologie. Ergebnisse hängen je Graph-Objekt im WeakMap-Cache,
+ * wie `moduleCrossings` — die Matrix ist O(n²) und wird je Voll-Lauf mehrfach gebraucht.
+ */
+import type { OntologyGraph } from './ontology.js';
+/** Wort-Token >= 3 Zeichen, lowercase, Unicode-Buchstaben/Ziffern. */
+export declare function tokens(s: unknown): Set<string>;
+/** Jaccard-Aehnlichkeit; leer/leer = 1 (identisch leer). */
+export declare function jaccard(a: ReadonlySet<string>, b: ReadonlySet<string>): number;
+export interface SimilarityMatrix {
+    /** Element-uids in kanonischer Ordnung — der Index in `matrix`. */
+    readonly ids: readonly string[];
+    /** Symmetrisch, Diagonale 1. */
+    readonly matrix: readonly (readonly number[])[];
+}
+/** FUNC-Aehnlichkeit je Graph (ND-01). */
+export declare const funcSimilarity: (graph: OntologyGraph) => SimilarityMatrix;
+/** SCHEMA-Aehnlichkeit je Graph (ND-02, AO-D01). */
+export declare const schemaSimilarity: (graph: OntologyGraph) => SimilarityMatrix;
+/** Paare ueber der Schwelle, kanonisch geordnet (i < j) — die eine Schleife fuer alle drei Regeln. */
+export declare function pairsAbove(sim: SimilarityMatrix, threshold: number): Array<{
+    a: string;
+    b: string;
+    similarity: number;
+}>;

package/dist/se/similarity.js

@@ -0,0 +1,116 @@
+import { isValidTrace } from './meta-model.js';
+/** Wort-Token >= 3 Zeichen, lowercase, Unicode-Buchstaben/Ziffern. */
+export function tokens(s) {
+    const text = typeof s === 'string' ? s : '';
+    return new Set(text
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter(w => w.length >= 3));
+}
+/** Jaccard-Aehnlichkeit; leer/leer = 1 (identisch leer). */
+export function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter += 1;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 1 : inter / union;
+}
+/**
+ * Partner-uids eines Elements ueber LEGALE Traces der genannten Typen.
+ *
+ * CR-SM-286: der Legalitaetsfilter ist nicht Kosmetik. Ohne ihn aenderte eine grammatikwidrige
+ * Kante das Urteil: `se-rule-pair-legality.test.ts` (Pruefung A, CR-SM-278) meldete **35**
+ * Faelle, in denen ND-02 erst durch eine injizierte illegale Kante auf SCHEMA anschlug —
+ * `ACTOR -compose-> SCHEMA`, `CR -io-> SCHEMA`, `FLOW -compose-> SCHEMA` und so fort. Eine
+ * Regel, deren Verdikt an einer Kante haengt, die R-18 als `error` ablehnt, urteilt ueber einen
+ * Graphen, den es nicht geben darf.
+ */
+function partners(graph, id, traceTypes) {
+    const byType = new Map(graph.elements.map(e => [e.id, e.type]));
+    const out = new Set();
+    for (const t of graph.traces) {
+        if (!traceTypes.includes(t.type))
+            continue;
+        if (t.source !== id && t.target !== id)
+            continue;
+        const src = byType.get(t.source);
+        const tgt = byType.get(t.target);
+        if (!src || !tgt)
+            continue; // haengende Kante -> R-08, nicht hier
+        if (!isValidTrace({ source: src, target: tgt, type: t.type }))
+            continue;
+        out.add(t.source === id ? t.target : t.source);
+    }
+    return out;
+}
+/** Erstes Wort des Namens als Verb-Naeherung (FUNC-Namen: Verb-Objekt). */
+function firstWord(name) {
+    const text = typeof name === 'string' ? name : '';
+    return text.toLowerCase().split(/[^\p{L}\p{N}]+/u).find(w => w.length > 0) ?? '';
+}
+const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/** Feld-Menge eines SCHEMA: `attributes.fields` (Array), sonst Beschreibungs-Token. */
+function schemaFields(el) {
+    const fields = el.attributes?.fields;
+    if (Array.isArray(fields) && fields.length > 0) {
+        return new Set(fields.map(f => String(typeof f === 'object' && f !== null ? (f.name ?? JSON.stringify(f)) : f).toLowerCase()));
+    }
+    return tokens(el.description);
+}
+const CACHE = new WeakMap();
+function build(graph) {
+    // ND-01: 0.35*descr_jaccard + 0.25*verb_match + 0.25*io_topology + 0.15*req_overlap
+    const funcs = graph.elements.filter(e => e.type === 'FUNC').sort(byId);
+    const fDescr = funcs.map(f => tokens(f.description));
+    const fVerb = funcs.map(f => firstWord(f.name));
+    const fIo = funcs.map(f => partners(graph, f.id, ['io']));
+    const fReq = funcs.map(f => new Set(graph.traces.filter(t => t.type === 'satisfy' && t.source === f.id).map(t => t.target)));
+    const func = {
+        ids: funcs.map(f => f.id),
+        matrix: funcs.map((_, i) => funcs.map((_, j) => i === j ? 1
+            : 0.35 * jaccard(fDescr[i], fDescr[j])
+                + 0.25 * (fVerb[i] !== '' && fVerb[i] === fVerb[j] ? 1 : 0)
+                + 0.25 * jaccard(fIo[i], fIo[j])
+                + 0.15 * jaccard(fReq[i], fReq[j]))),
+    };
+    // ND-02: 0.50*field_jaccard + 0.30*descr_jaccard + 0.20*usage_overlap
+    const schemas = graph.elements.filter(e => e.type === 'SCHEMA').sort(byId);
+    const sFields = schemas.map(schemaFields);
+    const sDescr = schemas.map(s => tokens(s.description));
+    const sUse = schemas.map(s => partners(graph, s.id, ['relation', 'io', 'compose']));
+    const schema = {
+        ids: schemas.map(s => s.id),
+        matrix: schemas.map((_, i) => schemas.map((_, j) => i === j ? 1
+            : 0.5 * jaccard(sFields[i], sFields[j])
+                + 0.3 * jaccard(sDescr[i], sDescr[j])
+                + 0.2 * jaccard(sUse[i], sUse[j]))),
+    };
+    return { func, schema };
+}
+function similarities(graph) {
+    let s = CACHE.get(graph);
+    if (s === undefined) {
+        s = build(graph);
+        CACHE.set(graph, s);
+    }
+    return s;
+}
+/** FUNC-Aehnlichkeit je Graph (ND-01). */
+export const funcSimilarity = (graph) => similarities(graph).func;
+/** SCHEMA-Aehnlichkeit je Graph (ND-02, AO-D01). */
+export const schemaSimilarity = (graph) => similarities(graph).schema;
+/** Paare ueber der Schwelle, kanonisch geordnet (i < j) — die eine Schleife fuer alle drei Regeln. */
+export function pairsAbove(sim, threshold) {
+    const out = [];
+    for (let i = 0; i < sim.ids.length; i++) {
+        for (let j = i + 1; j < sim.ids.length; j++) {
+            const s = sim.matrix[i][j];
+            if (s >= threshold)
+                out.push({ a: sim.ids[i], b: sim.ids[j], similarity: s });
+        }
+    }
+    return out;
+}

package/dist/se/uc-quality-rules.js

@@ -32,26 +32,45 @@ export function uc02HasActor(graph) {
     // ueber Elemente und Traces), dann je UC nur noch Mitgliedschaft pruefen. Dieselbe Aussage,
     // dieselben Befunde in derselben Reihenfolge — die Iteration ueber `graph.elements` bleibt
     // die aeussere Schleife.
+    // CR-SM-266 D1/D4: die Regel prueft ERREICHBARKEIT statt Adjazenz.
+    //
+    // Bis hierher suchte sie einen io-Ziel-Treffer direkt am UC oder an dessen compose-Kind —
+    // also genau die beiden Kanten `ACTOR -io-> UC` und (ueber die FCHAIN) den Direktweg. Beide
+    // Patterns sind mit D1/D4 entfallen; die Regel waere damit UNERFUELLBAR geworden: sie haette
+    // einen Zustand verlangt, den R-18 im selben Lauf als ungueltige Kante ablehnt — der
+    // gegenlaeufige Fall aus Gate 4 des Grammatik-Reviews, und fuer den Nutzer eine Sackgasse
+    // statt eines Fehlers.
+    //
+    // Der tragende Pfad ist jetzt der einzige: `ACTOR -io-> FLOW -io-> FUNC`, FUNC in einer
+    // FCHAIN des UC. Zwei Sprungweiten (Actor→FLOW, FLOW→FUNC), danach Mengen-Mitgliedschaft —
+    // die CR-SM-261-Optimierung bleibt damit erhalten (kein Scan je UC, alles ueber den Index
+    // aus CR-SM-264), und die Iteration ueber `elementsOfType('UC')` bleibt die aeussere
+    // Schleife, also ist die Befundreihenfolge weiter die Graph-Reihenfolge (Gate 5).
     const idx = indexOf(graph);
     const actorIds = idx.idsOfType('ACTOR');
-    const actorIoTargets = new Set(idx.tracesOfType('io').filter(t => actorIds.has(t.source)).map(t => t.target));
-    const composeTargets = new Map();
-    for (const t of idx.tracesOfType('compose')) {
-        const list = composeTargets.get(t.source);
-        if (list)
-            list.push(t.target);
-        else
-            composeTargets.set(t.source, [t.target]);
+    // Schritt 1: die FLOWs, die ein ACTOR speist.
+    const actorFlows = new Set(idx.tracesOfType('io').filter(t => actorIds.has(t.source)).map(t => t.target));
+    // Schritt 2: die FUNCs, die an einem solchen FLOW haengen — in BEIDE Richtungen. Ein UC ist
+    // auch dann an einen Actor angebunden, wenn die Kette IHM etwas liefert (FUNC -io-> FLOW
+    // -io-> ACTOR), nicht nur wenn sie von ihm getriggert wird. Die alte Fassung sah nur die
+    // Trigger-Richtung, weil `ACTOR -io-> UC` nur so herum existierte.
+    const actorFacingFuncs = new Set();
+    for (const t of idx.tracesOfType('io')) {
+        if (actorFlows.has(t.source))
+            actorFacingFuncs.add(t.target);
+        if (actorIds.has(t.target) && idx.typeOf(t.source) === 'FLOW') {
+            for (const producer of idx.in(t.source, 'io'))
+                actorFacingFuncs.add(producer.source);
+        }
     }
     return idx.elementsOfType('UC')
-        .filter(uc => !actorIoTargets.has(uc.id) &&
-        !(composeTargets.get(uc.id) ?? []).some(target => actorIoTargets.has(target)))
+        .filter(uc => !idx.out(uc.id, 'compose').some(chain => idx.out(chain.target, 'compose').some(member => actorFacingFuncs.has(member.target))))
         .map(uc => ({
         rule_id: 'UC-02',
         severity: 'error',
         element_id: uc.id,
-        message: `${uc.id} has no ACTOR with io trace`,
-        fix_hint: 'Link an ACTOR via io trace to this UC or its FCHAIN',
+        message: `${uc.id} is not reachable from any ACTOR`,
+        fix_hint: 'Wire an ACTOR to a FLOW that feeds (or is fed by) a FUNC in one of this UC\'s function chains',
         context: { element_type: uc.type, element_name: uc.name },
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/contracts",
-  "version": "6.3.0",
+  "version": "10.0.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,7 +29,8 @@
     "check:grammar": "node scripts/check-grammar-version.mjs",
     "grammar:snapshot": "SE_WRITE_GRAMMAR_SNAPSHOT=1 vitest run tests/unit/se-grammar-invariant.test.ts",
     "prepublishOnly": "npm run build && npm run test",
-    "grammar:measure": "SE_MEASURE=1 vitest run tests/unit/se-grammar-measure.test.ts"
+    "grammar:measure": "SE_MEASURE=1 vitest run tests/unit/se-grammar-measure.test.ts",
+    "report:silence": "node scripts/rules-silence-report.mjs"
   },
   "dependencies": {
     "zod": "^4.3.6"