@sigloch/se-engine 1.0.0

package/dist/rule-apply.d.ts

@@ -0,0 +1,39 @@
+import type { OntologyGraph, RuleViolation } from '@sigloch/contracts/se';
+export interface ApplyResult {
+    /** graph' (a fresh object); === input topology when applied is false. */
+    graph: OntologyGraph;
+    applied: boolean;
+    /** The Format-E-style line applied (label only, not re-parsed). */
+    op?: string;
+    /** Why nothing was applied (when applied is false). */
+    reason?: string;
+}
+/**
+ * Apply one rule to a graph as a transforming operator.
+ *
+ * `knownViolations` (CR-SM-228): when the caller already has
+ * `evaluateAllRules`'s result (e.g. suggestEdits, which computes it
+ * once for the whole firing-rule set), pass it here to skip re-running the
+ * full rule evaluation per probe — measured as the other dominant cost
+ * alongside the structuredClone above. Omit it for the old behavior
+ * (evaluates fresh internally) -- existing 2-arg callers are unaffected.
+ *
+ * @returns graph' + whether an edit was applied. Deterministic.
+ */
+export declare function applyRule(rule: {
+    id: string;
+}, graph: OntologyGraph, knownViolations?: RuleViolation[]): ApplyResult;
+export interface DeltaMark {
+    ruleId: string;
+    applied: boolean;
+    op?: string;
+    /** True when applying the rule leaves the measured vector unchanged (noise / mis-classification candidate). */
+    emptyDelta: boolean;
+}
+/**
+ * Mark every firing Operator rule by whether its single additive edit moves the
+ * measured vector (`measure`, injected — typically `metrics` flattened to ℝ⁶
+ * via `toArray`; für Architektur-Deltas `metrics(g, {layer:'arch'})`).
+ * Deterministic; single application from baseline.
+ */
+export declare function markEmptyDelta(graph: OntologyGraph, measure: (g: OntologyGraph) => number[]): DeltaMark[];

package/dist/rule-apply.js

@@ -0,0 +1,136 @@
+/**
+ * Generischer Violation → additive-edge Applier (promotet aus aimpro
+ * src/spike/rule-apply.ts, CR-226/CR-230 → CR-SM-224).
+ *
+ * KEIN per-Rule-Autofix (~50 Transformationen, bewusst nicht): EIN generischer
+ * Hebel — eine Operator-Regel (rule-classify.ts) feuert, ihre erste
+ * RuleViolation benennt das Element und (oft) Kandidaten-Ziele; synthetisiert
+ * wird genau EINE meta-model-valide Trace → graph' mit veränderter Topologie
+ * (Δm ≠ 0 unter `metrics`).
+ *
+ * CR-230: Validität wird mit `isValidTrace` gegen die gespeicherten
+ * `element.type` geprüft, nicht über parseFormatE-Roundtrip — der Applier ist
+ * id-format-agnostisch (graphcode `TYPE-slug` genauso wie SemanticId-Fixtures).
+ *
+ * Constraint-/Ziel-Regeln transformieren nichts: `applied: false`, Graph
+ * unangetastet. Spike-2-Grenze bleibt in Kraft: die synthetisierte Kante ist
+ * ein generischer Trace — bewertet wird die RICHTUNG (Δm), nie der literale
+ * 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';
+/** Deterministic timestamp for synthesized traces (no Date.now — keeps metrics stable). */
+const APPLY_TS = '2026-07-26T00:00:00.000Z';
+/**
+ * Add one trace to graph' — a SHALLOW copy (new top-level object, new traces
+ * array with the addition appended), not a deep structuredClone. Safe because
+ * nothing downstream (metrics/buildAdjacency/projectLayer/evaluateAllRules)
+ * ever mutates a graph's elements or existing traces in place — they only
+ * read. `elements` keeps the same array reference (never touched here);
+ * `traces` is a fresh array so the caller's original graph is untouched.
+ * CR-SM-228: structuredClone of the whole graph per probe was the dominant
+ * cost in suggestEdits' probe loop (measured ~20ms/call on a 382-node graph,
+ * ~249ms across 12 probes) — a shallow copy of an additive-only change costs
+ * a fraction of that.
+ */
+function addTrace(graph, source, target, type) {
+    return {
+        ...graph,
+        traces: [...graph.traces, { source, target, type, weight: 1, created_at: APPLY_TS }],
+    };
+}
+/**
+ * Apply one rule to a graph as a transforming operator.
+ *
+ * `knownViolations` (CR-SM-228): when the caller already has
+ * `evaluateAllRules`'s result (e.g. suggestEdits, which computes it
+ * once for the whole firing-rule set), pass it here to skip re-running the
+ * full rule evaluation per probe — measured as the other dominant cost
+ * alongside the structuredClone above. Omit it for the old behavior
+ * (evaluates fresh internally) -- existing 2-arg callers are unaffected.
+ *
+ * @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) {
+        return { graph, applied: false, reason: 'rule does not fire on this graph (empty Δm)' };
+    }
+    if (cls.class !== 'Operator') {
+        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]));
+    const v = violations[0];
+    const source = v.element_id;
+    const srcType = typeById.get(source);
+    if (!srcType)
+        return { graph, applied: false, reason: 'violation element not in graph' };
+    const neighbours = new Set();
+    for (const t of graph.traces) {
+        if (t.source === source)
+            neighbours.add(t.target);
+        if (t.target === source)
+            neighbours.add(t.source);
+    }
+    // Candidate partners: violation's ranked candidate_targets first, then any node.
+    const partners = [
+        ...(v.context?.candidate_targets ?? []).map((c) => c.id),
+        ...graph.elements.map((e) => e.id),
+    ].filter((id, i, a) => id !== source && !neighbours.has(id) && a.indexOf(id) === i);
+    // Trace types: the fix_hint's type first, then the rest.
+    const inferred = inferTraceType(v.fix_hint);
+    const traceTypes = [inferred, ...TRACE_KEYWORDS.filter((t) => t !== inferred)];
+    for (const partner of partners) {
+        const tgtType = typeById.get(partner);
+        if (!tgtType)
+            continue;
+        for (const tt of traceTypes) {
+            for (const [s, sType, t, tType] of [
+                [source, srcType, partner, tgtType],
+                [partner, tgtType, source, srcType],
+            ]) {
+                if (isValidTrace({ source: sType, target: tType, type: tt })) {
+                    return { graph: addTrace(graph, s, t, tt), applied: true, op: `+ ${s} -${tt}-> ${t}` };
+                }
+            }
+        }
+    }
+    return { graph, applied: false, reason: 'no meta-model-valid additive edit available' };
+}
+/**
+ * Mark every firing Operator rule by whether its single additive edit moves the
+ * measured vector (`measure`, injected — typically `metrics` flattened to ℝ⁶
+ * via `toArray`; für Architektur-Deltas `metrics(g, {layer:'arch'})`).
+ * Deterministic; single application from baseline.
+ */
+export function markEmptyDelta(graph, measure) {
+    const base = measure(graph);
+    const allViolations = evaluateAllRules(graph, MT_IRRELEVANT_POLICY);
+    const firingOperators = [...new Set(allViolations.map((v) => v.rule_id))]
+        .filter((id) => classOf(id).class === 'Operator');
+    return firingOperators.map((ruleId) => {
+        const res = applyRule({ id: ruleId }, graph, allViolations);
+        const after = res.applied ? measure(res.graph) : base;
+        return { ruleId, applied: res.applied, op: res.op, emptyDelta: after.every((x, i) => x === base[i]) };
+    });
+}
+/** Trace types the meta-model accepts (ontology TraceType enum). */
+const TRACE_KEYWORDS = ['verify', 'satisfy', 'allocate', 'compose', 'produces', 'io', 'relation'];
+/**
+ * Best-effort trace type from the violation's fix_hint (topology-only — the
+ * exact type does not affect `metrics`, but a plausible one keeps the edit
+ * legible). Defaults to 'relation'.
+ */
+function inferTraceType(fixHint) {
+    const h = (fixHint ?? '').toLowerCase();
+    for (const t of TRACE_KEYWORDS) {
+        if (new RegExp(`\\b${t}\\b`).test(h))
+            return t;
+    }
+    return 'relation';
+}

package/dist/rule-classify.d.ts

@@ -0,0 +1,43 @@
+import type { MetricPolicy } from '@sigloch/contracts/se';
+export type RuleClass = 'Operator' | 'Constraint' | 'Ziel';
+/**
+ * Die Policy, mit der der Optimizer Regeln auswertet (CR-SM-233).
+ *
+ * MT-01/MT-02 sind **Constraints** (siehe `CLASS_MAP`), und `applyRule`/`suggestEdits`
+ * verwerfen alles, was nicht `Operator` ist — eine Instabilitäts-Schwelle kann das Ranking
+ * hier also nachweislich nicht verändern. Statt eine unvalidierte Zahl mitzuschleppen,
+ * die keine Wirkung hat, wertet der Optimizer messend statt urteilend aus. Der Host, der
+ * wirklich urteilt (graphcode-Config), reicht seine eigene Policy an `evaluateAllRules`.
+ */
+export declare const MT_IRRELEVANT_POLICY: MetricPolicy;
+export interface Classification {
+    class: RuleClass;
+    /** One-line reason, cold-reader-safe. */
+    rationale: string;
+    /** True when Operator vs Constraint is genuinely unclear (mixed-intent fix). */
+    ambiguous?: boolean;
+}
+/** Static classification keyed by rule_id. Authoritative; see file header. */
+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;
+export interface ClassifiedRule {
+    id: string;
+    name: string;
+    severity: 'error' | 'warning' | 'info';
+    class: RuleClass;
+    rationale: string;
+    ambiguous: boolean;
+}
+/** Classify the entire live rule catalog (ALL_RULE_DEFS). */
+export declare function classifyAll(): ClassifiedRule[];
+export interface ClassificationStats {
+    total: number;
+    operators: number;
+    constraints: number;
+    ziele: number;
+    ambiguous: number;
+    /** Share of rules with a definite (non-ambiguous) class. */
+    eindeutigShare: number;
+}
+export declare function classificationStats(rules?: ClassifiedRule[]): ClassificationStats;

package/dist/rule-classify.js

@@ -0,0 +1,163 @@
+/**
+ * Rule-Klassifikation Operator/Constraint/Ziel (promotet aus aimpro
+ * src/spike/rule-classify.ts, CR-226 → CR-SM-224).
+ *
+ * Jede SE-Regel im Live-Katalog (@sigloch/contracts/se → ALL_RULE_DEFS) ist ein
+ * Check `evaluate(graph) → RuleViolation[]`. Der Optimierer braucht die Teilung:
+ *   - Operator   — der Fix FÜGT eine Trace/ein Element HINZU → Topologie ändert
+ *                  sich → nutzbar als transformierende Aktion (applyRule, J).
+ *   - Constraint — der Fix entfernt/repariert/reduziert Bestehendes oder ist
+ *                  attribut-/textbasiert (keine Topologieänderung) → Gate-Kandidat.
+ *   - Ziel       — rein bewertend, kein lokaler Fix.
+ *
+ * Befund (Spike 1): der SE-Katalog enthält nur Operatoren und Constraints; der
+ * "Ziel"-Eimer ist leer — die sechs Zielvektoren sind keine Regeln, sondern
+ * `metrics()` (src/metrics.ts). Attribut-only-additive Fixes (realRef/testRefs/
+ * description) sind Constraints: sie fügen keine Trace/keinen Knoten hinzu,
+ * also kann `applyRule` `metrics` nicht bewegen. Echte Mischfälle tragen
+ * `ambiguous: true`.
+ *
+ * Delta zum Spike-Original: RD-04 (Dekompositionsbreite, CR-SM-221) ergänzt;
+ * SC-01/SC-03 (BOK-CR-026) und MT-03 (CR-SM-223) sind aus dem Katalog gelöscht
+ * und daher hier entfernt. CR-SM-226: +R-28/FC-04/SC-04 (neue Regeln); IO-01
+ * ist nicht mehr cross-module-only (Rationale-Text angepasst, Klasse unverändert).
+ * CR-GC-366: +R-30 (Wirkketten-Bindung) und +R-31 (io-Verdrahtung), beide Operator —
+ * ihr Fix fügt eine Trace hinzu und bewegt damit die Topologie.
+ */
+import { ALL_RULE_DEFS } from '@sigloch/contracts/se';
+import { DEFAULT_METRIC_POLICY } from '@sigloch/contracts/se';
+/**
+ * Die Policy, mit der der Optimizer Regeln auswertet (CR-SM-233).
+ *
+ * MT-01/MT-02 sind **Constraints** (siehe `CLASS_MAP`), und `applyRule`/`suggestEdits`
+ * verwerfen alles, was nicht `Operator` ist — eine Instabilitäts-Schwelle kann das Ranking
+ * hier also nachweislich nicht verändern. Statt eine unvalidierte Zahl mitzuschleppen,
+ * die keine Wirkung hat, wertet der Optimizer messend statt urteilend aus. Der Host, der
+ * wirklich urteilt (graphcode-Config), reicht seine eigene Policy an `evaluateAllRules`.
+ */
+export const MT_IRRELEVANT_POLICY = {
+    // CR-SM-236: als Abweichung VOM Startwert formuliert, nicht als eigene Werteliste. Waechst
+    // die Policy um eine weitere Schwelle, urteilt der Optimizer weiter wie der Rest der Familie,
+    // statt sie stillschweigend stillzulegen.
+    //
+    // Nur MT-01/MT-02 sind hier neutralisiert. CR-01, FM-03 und R-04 behalten ihre Schwelle:
+    // FM-03 ist **Operator** (`CLASS_MAP`) — der Optimizer handelt auf seinen Befunden. Es auf
+    // `null` zu setzen haette den Vorschlag "TEST(passed) + verify an das Risiko-REQ" ersatzlos
+    // entfernt, also die Bewertung geaendert statt nur ihre Herkunft.
+    ...DEFAULT_METRIC_POLICY,
+    instability: null,
+    lcom4: null,
+};
+/** Static classification keyed by rule_id. Authoritative; see file header. */
+export const CLASS_MAP = {
+    // --- Operators: fix adds a trace/element (topology-changing) ---------------
+    'R-01': { class: 'Operator', rationale: 'add verify trace REQ←TEST' },
+    'R-02': { class: 'Operator', rationale: 'add satisfy trace FUNC→REQ' },
+    'R-05': { class: 'Operator', rationale: 'add verify trace TEST→REQ' },
+    'R-10': { class: 'Operator', rationale: 'add io traces to complete the FLOW' },
+    'R-14': { class: 'Operator', rationale: 'add compose trace UC→FCHAIN/REQ' },
+    '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' },
+    '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' },
+    'MS-01': { class: 'Operator', rationale: 'add CR→MS relation trace (scope)' },
+    'MS-03': { class: 'Operator', rationale: 'add CR→MS relation trace (assign milestone)' },
+    'UC-01': { class: 'Operator', rationale: 'add compose trace UC→REQ' },
+    'UC-02': { class: 'Operator', rationale: 'add io trace UC←ACTOR' },
+    'UC-03': { class: 'Operator', rationale: 'add compose trace UC→FCHAIN (scenario)' },
+    'UC-05': { class: 'Operator', rationale: 'add REQ(postcondition) via compose trace' },
+    'UC-06': { class: 'Operator', rationale: 'add REQ(precondition) via compose trace' },
+    'FC-01': { class: 'Operator', rationale: 'connect chain to ACTOR via FLOW io trace' },
+    'FC-02': { class: 'Operator', rationale: 'add FCHAIN via compose trace to leaf UC' },
+    'SC-02': { class: 'Operator', rationale: 'link FLOW→SCHEMA via relation trace' },
+    'PH-01': { class: 'Operator', rationale: 'add logical MOD via compose trace' },
+    'IO-01': { class: 'Operator', rationale: 'add FLOW element + io traces between the FUNC pair' },
+    'R-28': { class: 'Operator', rationale: 'add FLOW/SCHEMA element(s) to bind architecture levels' },
+    // CR-GC-366: beide Fixes fuegen eine Trace hinzu, also Operator wie R-15 (compose) und R-10 (io).
+    'R-30': { class: 'Operator', rationale: 'add compose trace FCHAIN→FUNC to bind the function into a chain' },
+    'R-31': { class: 'Operator', rationale: 'add io traces FLOW→FUNC / FUNC→FLOW to wire the function up' },
+    'FC-04': { class: 'Operator', rationale: 'add ACTOR→FLOW entry + FUNC→FLOW exit io traces' },
+    'SC-04': { class: 'Operator', rationale: 'link FLOW→SCHEMA via relation trace' },
+    'CR-R01': { class: 'Operator', rationale: 'add relation traces CR→affected elements' },
+    'CR-R04': { class: 'Operator', rationale: 'add relation trace CR→FUNC' },
+    'FM-02': { class: 'Operator', rationale: 'create mitigation REQ + compose trace' },
+    'FM-03': { class: 'Operator', rationale: 'add TEST(passed) + verify trace to risk REQ' },
+    // --- Constraints: remove/repair/reduce, or attribute/text-only -------------
+    'R-03': { class: 'Constraint', rationale: 'ASIL isolation — separate mixed levels, non-additive' },
+    'R-04': { class: 'Constraint', rationale: 'module too large — split, non-additive' },
+    'R-08': { class: 'Constraint', rationale: 'repair dangling trace endpoint' },
+    'R-12': { class: 'Constraint', rationale: 'break dependency cycle — remove an edge' },
+    'R-18': { class: 'Constraint', rationale: 'invalid trace pattern — change/remove trace' },
+    'R-19': { class: 'Constraint', rationale: 'add testRefs attribute — no topology change' },
+    // CR-SM-231: R-29 ist NICHT additiv aufloesbar. Der Fix nimmt einen Anspruch WEG, und welcher
+    // der konkurrierenden TESTs die Datei wirklich belegt, ist eine fachliche Entscheidung —
+    // kein Attribut, das der Optimizer setzen koennte.
+    'R-29': { class: 'Constraint', rationale: 'test file claimed twice — which acceptance owns it is a judgement call' },
+    'R-20': { class: 'Constraint', rationale: 'add realRef attribute — no topology change' },
+    'R-26': { class: 'Constraint', rationale: 'add realRef attribute — no topology change' },
+    'R-27': { class: 'Constraint', rationale: 'physical MOD add realRef attribute — no topology change' },
+    'RD-02': { class: 'Constraint', rationale: 'decomposition consistency — repair existing' },
+    'RD-03': { class: 'Constraint', rationale: 'premature decomposition — remove children' },
+    'RD-04': { class: 'Constraint', rationale: 'decomposition breadth 7–11 — split level, non-additive' },
+    'MS-02': { class: 'Constraint', rationale: 'dangling dependency — fix relation target' },
+    'UC-04': { class: 'Constraint', rationale: 'goal = description text — no topology change' },
+    'FC-03': { class: 'Constraint', rationale: 'flatten chain — move nested funcs' },
+    'MT-01': { class: 'Constraint', rationale: 'instability threshold — restructure' },
+    'MT-02': { class: 'Constraint', rationale: 'cohesion (LCOM4) threshold — restructure' },
+    'BQ-01': { class: 'Constraint', rationale: 'unambiguous — text quality' },
+    'BQ-02': { class: 'Constraint', rationale: 'verifiable — text quality' },
+    'BQ-04': { class: 'Constraint', rationale: 'necessary — text/scope quality' },
+    'BQ-06': { class: 'Constraint', rationale: 'conforming — text/format quality' },
+    'BQ-07': { class: 'Constraint', rationale: 'complete — text quality' },
+    'ND-01': { class: 'Constraint', rationale: 'near-duplicate FUNC — merge/differentiate' },
+    'ND-02': { class: 'Constraint', rationale: 'near-duplicate SCHEMA — merge/differentiate' },
+    'CR-R02': { class: 'Constraint', rationale: 'done requires commitRef — attribute' },
+    'CR-R03': { class: 'Constraint', rationale: 'concurrent mutation — coordinate, non-additive' },
+    'AO-D01': { class: 'Constraint', rationale: 'relay node — eliminate/rewire, advisory' },
+    'AO-D03': { class: 'Constraint', rationale: 'duplicate path — unify, advisory' },
+    'CR-01': { class: 'Constraint', rationale: 'crossing-flow coupling — reduce, advisory' },
+    'RT-01': { class: 'Constraint', rationale: 'physical boundary integrity — repair' },
+    'NFR-01': { class: 'Constraint', rationale: 'budget overshoot — reduce measured/raise budget' },
+    'VR-01': { class: 'Constraint', rationale: 'missing testResult attribute — no topology change' },
+    // CR-SM-227 hat AF-01..05 in den Katalog gelegt, ohne sie hier zu klassifizieren;
+    // der Deckungstest fiel erst auf, als contracts neu gebaut wurde (stale dist).
+    // Ein Freshness-Stamp ist ein Attribut am bestehenden Knoten — keine neue Kante.
+    'AF-01': { class: 'Constraint', rationale: 'ConOps freshness stamp — attribute, no topology change' },
+    'AF-02': { class: 'Constraint', rationale: 'Trade Study freshness stamp — attribute, no topology change' },
+    'AF-03': { class: 'Constraint', rationale: 'Assumption Review freshness stamp — attribute, no topology change' },
+    'AF-04': { class: 'Constraint', rationale: 'FMEA freshness stamp — attribute, no topology change' },
+    'AF-05': { class: 'Constraint', rationale: 'Implementation Plan freshness stamp — attribute, no topology change' },
+    // --- Ambiguous (mixed-intent fix) ------------------------------------------
+    'CA-01': { class: 'Constraint', rationale: 'add capabilities OR move FUNC — mixed', ambiguous: true },
+    'CL-01': { class: 'Constraint', rationale: 'ConOps completeness — attribute vs added element unclear', ambiguous: true },
+    'FM-01': { class: 'Constraint', rationale: 'FMEA S/O/D attributes vs added mitigation — mixed', ambiguous: true },
+};
+const UNKNOWN = { class: 'Constraint', rationale: 'unclassified — not in CLASS_MAP', ambiguous: true };
+/** Classify a single rule id (falls back to ambiguous-unknown). */
+export function classOf(ruleId) {
+    return CLASS_MAP[ruleId] ?? UNKNOWN;
+}
+/** Classify the entire live rule catalog (ALL_RULE_DEFS). */
+export function classifyAll() {
+    return ALL_RULE_DEFS.map((r) => {
+        const c = classOf(r.id);
+        return { id: r.id, name: r.name, severity: r.severity, class: c.class, rationale: c.rationale, ambiguous: c.ambiguous ?? false };
+    });
+}
+export function classificationStats(rules = classifyAll()) {
+    const operators = rules.filter((r) => r.class === 'Operator').length;
+    const constraints = rules.filter((r) => r.class === 'Constraint').length;
+    const ziele = rules.filter((r) => r.class === 'Ziel').length;
+    const ambiguous = rules.filter((r) => r.ambiguous).length;
+    return {
+        total: rules.length,
+        operators,
+        constraints,
+        ziele,
+        ambiguous,
+        eindeutigShare: rules.length === 0 ? 0 : (rules.length - ambiguous) / rules.length,
+    };
+}

package/dist/suggest.d.ts

@@ -0,0 +1,31 @@
+import type { OntologyGraph } from '@sigloch/contracts/se';
+import { type MetricVector } from './metrics.js';
+import type { MetricLayer } from './layer.js';
+import { type SuggestedEdit } from './fix-templates.js';
+/** Build a target vector (ℝ⁶, canonical dimension order) from named metric weights. */
+export declare function targetFor(weights: Partial<Record<keyof MetricVector, number>>): number[];
+export interface Suggestion {
+    ruleId: string;
+    /** Fund: das verletzte Element. */
+    elementId: string;
+    /** Fund: die Regel-Botschaft (erste Violation der Regel). */
+    message: string;
+    fixHint?: string;
+    /** Δm der generischen Richtungssonde (ℝ⁶, kanonische Ordnung). */
+    delta: number[];
+    /** Projektion von Δm auf das Einheitsziel: >0 hin, <0 weg. */
+    score: number;
+    /** Rule-spezifischer Template-Edit; fehlt = Fund-Ebene ohne Edit. */
+    edit?: SuggestedEdit;
+}
+export interface SuggestOptions {
+    /** Top-k (Default: alle). */
+    k?: number;
+    /** Messebene für Δm — 'arch' für Architektur-Deltas (CR-AIM-235 §3). */
+    layer?: MetricLayer;
+}
+/**
+ * Rank the firing Operator rules by how much their probe edit moves `graph`
+ * toward `target`. Deterministic, score-descending, tiebreak ruleId.
+ */
+export declare function suggestEdits(graph: OntologyGraph, target: number[], opts?: SuggestOptions): Suggestion[];

package/dist/suggest.js

@@ -0,0 +1,63 @@
+/**
+ * Greedy one-step optimization suggestions (promotet aus aimpro
+ * src/spike/suggest.ts, CR-234 → CR-SM-225) — MIT dem Spike-2-Redesign:
+ *
+ * AUSGELIEFERT wird die Fund-Ebene: Violation (Element + Message) + Richtung
+ * (score = Δm·t̂) + Δm. Der generische applyRule-Trace bleibt eine interne
+ * Richtungssonde — als Edit ausgeliefert wird NUR, was ein rule-spezifisches
+ * Fix-Template (fix-templates.ts) deterministisch aus dem Elementtext herleitet.
+ * Δm rankt, es gibt nie frei: Anwendung läuft immer durchs Gate (3-Tier-Verdict,
+ * graphcode graph_suggest → dryRun-Preview), nie auto-apply.
+ *
+ * Bewusst EIN Schritt von der Baseline — kein Sequencing, keine Interaktion,
+ * keine Pareto-Front, keine Suche (Fahrplan-Schritt 5).
+ */
+import { evaluateAllRules } from '@sigloch/contracts/se';
+import { metrics, toArray, METRIC_DIMENSIONS } from './metrics.js';
+import { applyRule } from './rule-apply.js';
+import { classOf, MT_IRRELEVANT_POLICY } from './rule-classify.js';
+import { fixFor } from './fix-templates.js';
+/** Build a target vector (ℝ⁶, canonical dimension order) from named metric weights. */
+export function targetFor(weights) {
+    return METRIC_DIMENSIONS.map((d) => weights[d] ?? 0);
+}
+function l2(v) {
+    return Math.sqrt(v.reduce((s, x) => s + x * x, 0));
+}
+/**
+ * Rank the firing Operator rules by how much their probe edit moves `graph`
+ * toward `target`. Deterministic, score-descending, tiebreak ruleId.
+ */
+export function suggestEdits(graph, target, opts = {}) {
+    const { k = Infinity, layer = 'all' } = opts;
+    const tn = l2(target);
+    const t = tn < 1e-12 ? target : target.map((x) => x / tn);
+    const measure = (g) => toArray(metrics(g, { layer }));
+    const base = measure(graph);
+    const violations = evaluateAllRules(graph, MT_IRRELEVANT_POLICY);
+    const firstByRule = new Map();
+    for (const v of violations)
+        if (!firstByRule.has(v.rule_id))
+            firstByRule.set(v.rule_id, v);
+    const suggestions = [];
+    for (const [ruleId, v] of firstByRule) {
+        if (classOf(ruleId).class !== 'Operator')
+            continue;
+        const probe = applyRule({ id: ruleId }, graph, violations);
+        if (!probe.applied)
+            continue;
+        const delta = measure(probe.graph).map((x, i) => x - base[i]);
+        const score = delta.reduce((s, x, i) => s + x * t[i], 0);
+        suggestions.push({
+            ruleId,
+            elementId: v.element_id,
+            message: v.message,
+            fixHint: v.fix_hint,
+            delta,
+            score,
+            edit: fixFor(v, graph) ?? undefined,
+        });
+    }
+    suggestions.sort((a, b) => b.score - a.score || a.ruleId.localeCompare(b.ruleId));
+    return Number.isFinite(k) ? suggestions.slice(0, k) : suggestions;
+}

package/dist/topology.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure topological graph primitives over OntologyGraph (ported from aimpro
+ * src/harness/topology.ts, CR-224; extended with optional node weights for
+ * CR-AIM-235).
+ *
+ * Semantikfrei — no element type, attribute or trace semantics enter here;
+ * only nodes and directed/undirected connectivity. These primitives feed
+ * `metrics()` (src/metrics.ts), which maps them onto the 6 Zielvektoren.
+ *
+ * Weights: `buildAdjacency(graph, nodeWeight?)` derives symmetric edge weights
+ * w(v,w) = (m(v)+m(w))/2 from node masses (default mass 1). With no weight map
+ * every weight is 1 and all weighted quantities reduce EXACTLY to the
+ * unweighted originals (regression invariant). Community structure (Q, CNM,
+ * intra-edge fraction) and component mass read weights; betweenness,
+ * cyclomatic redundancy and source→sink paths stay unweighted by design —
+ * they measure routing/shape, not mass.
+ *
+ * All functions are deterministic (fixed node iteration order = graph order,
+ * ties broken by id) and dependency-free.
+ */
+import type { OntologyGraph } from '@sigloch/contracts/se';
+/** Directed + undirected adjacency, plus stable node ordering and edge weights. */
+export interface Adjacency {
+    /** Node ids in stable order (graph element order). */
+    nodes: string[];
+    /** Undirected neighbours (deduped, self-loops removed). */
+    undirected: Map<string, Set<string>>;
+    /** Directed successors (source → targets). */
+    out: Map<string, Set<string>>;
+    /** Directed predecessors (target → sources). */
+    in: Map<string, Set<string>>;
+    /** Symmetric undirected edge weights; 1 for every edge when unweighted. */
+    w: Map<string, Map<string, number>>;
+    /** Node mass (nodeWeight input, default 1). */
+    mass: Map<string, number>;
+}
+/**
+ * Build adjacency maps from a graph. Traces referencing unknown nodes are
+ * dropped. `nodeWeight` (e.g. LOC per node, see layer.ts `weightNodes`) sets
+ * node masses; edge weight = mean of endpoint masses.
+ *
+ * ORDER-INVARIANT (CR-SM-240): `nodes` and every neighbour set come back in
+ * canonical id order, so the SAME graph in a different element/trace order
+ * yields a bit-identical Adjacency — and therefore bit-identical metrics.
+ */
+export declare function buildAdjacency(graph: OntologyGraph, nodeWeight?: Map<string, number>): Adjacency;
+/**
+ * Betweenness centrality (Brandes' algorithm, unweighted undirected), normalized
+ * to [0,1] by the number of ordered node pairs (n-1)(n-2). Returns 0 for all
+ * nodes when n < 3. Higher = more of the shortest paths route through the node
+ * (structural bottleneck).
+ *
+ * CR-SM-228: index-based typed arrays instead of a fresh Map<string,X> per BFS
+ * source. The algorithm and its output are unchanged (bit-identical to the
+ * prior Map-based version) -- only the per-source scratch state changes from
+ * "allocate 4 new Maps" (O(V) allocation repeated V times = O(V^2) overhead
+ * on top of Brandes' own O(V*E), dominant on sparse graphs) to "reset 4
+ * preallocated typed arrays via .fill()" (same O(V) work, without the
+ * allocation/hashing cost). Measured A/B (1910-node graph, 3915 edges,
+ * cloned from graphcode's own SSOT):
+ *   OLD per-source Map allocation : ~610 ms
+ *   NEW indexed typed arrays      : ~93 ms   (6.6x faster, max diff 0)
+ * Root cause + measurement: sigloch-modules/docs/cr/open/CR-SM-228-*.md.
+ */
+export declare function betweenness(adj: Adjacency): Map<string, number>;
+/** Max betweenness over all nodes (the worst bottleneck), in [0,1]. */
+export declare function maxBetweenness(adj: Adjacency): number;
+/**
+ * Newman modularity Q for a given community assignment, over weighted edges.
+ * Q = (1/2m) Σ_ij [A_ij − k_i k_j / 2m] δ(c_i,c_j) ∈ [-0.5, 1]. 0 when edgeless.
+ * Unweighted graphs (all edge weights 1) reproduce the classic unweighted Q.
+ */
+export declare function modularityOf(adj: Adjacency, community: Map<string, number>): number;
+/** Newman modularity Q of the graph under greedy CNM communities. */
+export declare function modularityQ(adj: Adjacency): number;
+/**
+ * Greedy agglomerative community detection (Clauset–Newman–Moore, weighted):
+ * start each node in its own community, repeatedly merge the edge-linked pair
+ * that most increases Q, until no merge helps. Returns node→community-id.
+ * Edgeless graph → singletons.
+ *
+ * DETERMINISM (CR-SM-240) — the claim used to be "ties broken by community-id
+ * order", which was only half true: the ids are `buildAdjacency`'s node indices,
+ * and those were the CALLER's element order. A tie then went to whoever came
+ * first in the input, so a permuted graph produced a different partition (and
+ * with it different `modifiability`/`coherence`). The ids are canonical since
+ * CR-SM-240, so the sentence now holds: `alive` iterates ascending (built 0..n-1,
+ * deletions preserve order), each `e[i]` row was filled in canonical node order,
+ * and the strict `dq > best` therefore keeps the FIRST maximum in ascending
+ * (i, k) order. The invariant lives in `buildAdjacency`; do not re-derive it here.
+ */
+export declare function detectCommunities(adj: Adjacency): Map<string, number>;
+/** Weakly-connected components (undirected reachability), as node-id groups. */
+export declare function components(adj: Adjacency): string[][];
+/** Weakly-connected component sizes (node counts). */
+export declare function componentSizes(adj: Adjacency): number[];
+/**
+ * Cyclomatic redundancy density = (m − n + c) / n, where m = undirected edges,
+ * n = nodes, c = components. Counts independent cycles per node — the redundant
+ * paths that survive a single edge/node failure. 0 for a forest. Unweighted.
+ */
+export declare function redundancyDensity(adj: Adjacency): number;
+/**
+ * Coupling/cohesion: the fraction of edge WEIGHT that stays INSIDE a community
+ * of the given partition (vs crossing between communities). ∈ [0,1]; higher =
+ * more cohesive / less coupled. Community-based, so non-trivial on the
+ * near-bipartite, layered SE ontology graph (CR-229). 0 when edgeless.
+ */
+export declare function intraEdgeFraction(adj: Adjacency, community: Map<string, number>): number;
+/**
+ * Mean shortest directed path length from sources (in-degree 0) to sinks
+ * (out-degree 0), over reachable source→sink pairs only. Returns
+ * { meanLength, reachableFraction }. When no source→sink pair is reachable,
+ * meanLength is 0 and reachableFraction is 0. Unweighted.
+ */
+export declare function sourceSinkPaths(adj: Adjacency): {
+    meanLength: number;
+    reachableFraction: number;
+};