@sigloch/graph-api-core 5.5.0 → 5.6.0

package/dist/format-e-codec.d.ts

@@ -29,6 +29,7 @@ export declare class FormatECodec {
      */
     serialize(graph: Graph, options?: {
         omitProvenance?: boolean;
+        roundTrip?: boolean;
     }): string;
     private parseNodeLine;
     private parseEdgeLine;
@@ -65,9 +66,32 @@ export declare class FormatECodec {
      * contains no comma. No edge in the SE ontology carries a structured attribute today; if one
      * ever does, the inline block is the thing to replace, not this escape.
      */
-    private serializeAttrs;
-    /** CR-GC-334: object/array attributes as `@key {json}` lines below the node entry. */
-    private structuredAttrLines;
+    /**
+     * CR-SM-332: EIN Kriterium entscheidet, ob ein Attribut inline oder auf eine `@key`-Zeile
+     * geht — naemlich, ob sein Wert den Inline-Block brechen wuerde.
+     *
+     * Vorher entschied der TYP: `typeof v === 'object'` ging auf die Folgezeile, alles andere
+     * inline. Damit blieb eine Luecke derselben Klasse wie der Zeilenumbruch offen: ein STRING
+     * mit Komma oder Klammer ("a, b" oder "f(x)") wurde inline geschrieben, und
+     * `parseInlineAttrs` splittet auf Kommas — der Wert kam zerteilt oder gar nicht zurueck.
+     * Still, wie immer bei dieser Klasse. graphcodes Fork hatte genau dafuer bereits
+     * `UNSAFE_ATTR_RE`; die Regel wandert hierher, wo der einzige Codec steht.
+     *
+     * Schluessel aufsteigend nach Code-Einheiten, nicht `localeCompare` — dieselbe Begruendung
+     * wie bei `serializeEdges`: eine Sortierung, die von der Locale abhaengt, ist nicht
+     * deterministisch.
+     */
+    private nodeAttrParts;
+    /**
+     * CR-SM-332 (aus graphcodes Fork uebernommen, CR-GC-200/CR-GC-531): Knotentypen gegen die
+     * Ontologie, Kantentypen gegen die Ontologie, doppelte uids, aufloesbare Endpunkte.
+     * Paar-Legalitaet gehoert NICHT hierher — das ist R-18, dort wo Daten in den Speicher
+     * gehen.
+     */
+    validate(graph: Graph, resolveType?: (uid: string) => string | undefined): {
+        valid: boolean;
+        errors: string[];
+    };
     /** Inline block for an EDGE — structured values stringified, see `serializeAttrs`. */
     private serializeEdgeAttrs;
     private edgeTypeToArrow;

package/dist/format-e-codec.js

@@ -22,6 +22,35 @@ const MERGE_RE = /^M\s+(.+)$/;
 const FORMAT_E_FENCE = /```format-e\s*\n([\s\S]*?)```/;
 /** Inline attribute block: [key:value,key:value] */
 const INLINE_ATTRS_RE = /\[([^\]]+)\]$/;
+/**
+ * CR-SM-332 (ITEM-2026-183) — Format E ist ZEILENBASIERT, also darf kein Feld eine Zeile
+ * beenden koennen. `serialize` schrieb `|${description}` roh hinaus; eine Beschreibung mit
+ * `\n` erzeugte damit eine zweite Zeile, die beim naechsten Lesen als eigener KNOTEN ankam
+ * (uid = der Resttext, Typ = die offene `### <TYPE>`-Sektion). Am Gate reproduziert: success
+ * true, mutations 2 — der Phantom-Knoten waere angelegt worden.
+ *
+ * Beide Enden sind noetig. Nur lesend zu pruefen hiesse, der kaputte Text entsteht weiter und
+ * faellt erst beim naechsten Lesen auf — dann ohne den Knoten, der ihn verursacht hat.
+ */
+const LINE_BREAK_RE = /[\r\n]/;
+/**
+ * CR-SM-332: Zeichen, an denen der Inline-Block `[k:v,k:v]` zerbricht. `parseInlineAttrs`
+ * splittet auf Kommas, also kann kein Wert mit Komma oder Klammer dort stehen — gleich ob er
+ * ein Objekt ist oder ein String. Uebernommen aus graphcodes Fork (UNSAFE_ATTR_RE).
+ */
+const UNSAFE_INLINE_RE = /[,[\]{}]/;
+/**
+ * Vergleich nach CODE-EINHEITEN, nicht `localeCompare`: eine Sortierung, die von der Locale
+ * des laufenden Prozesses abhaengt, ist nicht deterministisch (REQ-deterministic-serialization).
+ */
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function assertSingleLine(where, field, value) {
+    if (typeof value === 'string' && LINE_BREAK_RE.test(value)) {
+        throw new Error(`FormatECodec.serialize: ${where} — ${field} enthaelt einen Zeilenumbruch. Format E ist `
+            + `zeilenbasiert; der Umbruch wuerde beim Lesen als eigene Knotenzeile ankommen `
+            + `(ITEM-2026-183). Ein langer Text gehoert zerlegt, nicht umgebrochen.`);
+    }
+}
 export class FormatECodec {
     ontology;
     edgeArrowToType;
@@ -157,6 +186,17 @@ export class FormatECodec {
      */
     serialize(graph, options = {}) {
         const omit = options.omitProvenance === true;
+        const roundTrip = options.roundTrip === true;
+        // CR-SM-332: `roundTrip` ist die Fassung, die graphcode bis hierher als EIGENEN encode
+        // nachgebaut hat (projections/codec.ts) — sie traegt zusaetzlich die Felder, die neben
+        // `attributes` leben (name/createdAt/updatedAt), und prueft den Graphen vorher. Kein
+        // zweiter Codec, eine Option: der Standard bleibt zeichengleich die Agenten-Sicht.
+        if (roundTrip) {
+            const { valid, errors } = this.validate(graph);
+            if (!valid) {
+                throw new Error(`FormatECodec.serialize: graph validation failed:\n  - ${errors.join('\n  - ')}`);
+            }
+        }
         const lines = [];
         if (graph.nodes.length > 0) {
             lines.push('## Nodes');
@@ -173,13 +213,38 @@ export class FormatECodec {
             }
             for (const type of [...byType.keys()].sort()) {
                 lines.push(`### ${type}`);
-                for (const node of byType.get(type) ?? []) {
-                    const descr = node.description ? `|${node.description}` : '';
-                    const nodeAttrs = omit ? stripNodeProvenance(node.attributes) : node.attributes;
-                    lines.push(`+ ${node.uid}${descr}${this.serializeAttrs(nodeAttrs)}`);
-                    // CR-GC-334: realRef/testRef & friends as @key {json} — the inline block above
-                    // cannot carry them, and dropping them here is what made bindings vanish.
-                    lines.push(...this.structuredAttrLines(nodeAttrs));
+                // CR-SM-332: innerhalb der Sektion nach uid sortiert. Vorher stand hier die
+                // EINGABEREIHENFOLGE — zwei encode-Laeufe auf demselben Graphen konnten sich also
+                // unterscheiden, sobald der Speicher anders lieferte. Das war der Grund, aus dem
+                // graphcode einen eigenen encode hielt (REQ-deterministic-serialization).
+                const group = [...(byType.get(type) ?? [])].sort((a, b) => cmp(a.uid, b.uid));
+                for (const node of group) {
+                    // CR-SM-332: kein Umbruch verlaesst diesen Codec.
+                    assertSingleLine(`node "${node.uid}"`, 'description', node.description);
+                    const base = omit ? stripNodeProvenance(node.attributes) : node.attributes;
+                    // Die Felder, die NEBEN `attributes` am Knoten haengen — ohne sie ist
+                    // decode(encode(g)) nicht deep-equal g. Nur in der Rundlauf-Fassung: in der
+                    // Agenten-Sicht waere `__name` an jedem Knoten reines Rauschen.
+                    const nodeAttrs = roundTrip
+                        ? {
+                            ...base,
+                            __name: node.name,
+                            ...(node.createdAt !== undefined ? { __createdAt: node.createdAt } : {}),
+                            ...(node.updatedAt !== undefined ? { __updatedAt: node.updatedAt } : {}),
+                        }
+                        : base;
+                    for (const [k, v] of Object.entries(nodeAttrs)) {
+                        // Strukturierte Werte gehen als JSON auf @key-Zeilen; JSON.stringify maskiert
+                        // den Umbruch, dort kann er die Zeile nicht brechen.
+                        if (typeof v !== 'object')
+                            assertSingleLine(`node "${node.uid}"`, `attribute "${k}"`, v);
+                    }
+                    // In der Rundlauf-Fassung steht der Pipe IMMER: ohne ihn kaeme eine leere
+                    // Beschreibung als `undefined` zurueck statt als '' (graphcodes encode tat dasselbe).
+                    const descr = node.description ? `|${node.description}` : (roundTrip ? '|' : '');
+                    const { inline, follow } = this.nodeAttrParts(nodeAttrs);
+                    lines.push(`+ ${node.uid}${descr}${inline}`);
+                    lines.push(...follow);
                 }
             }
         }
@@ -189,6 +254,14 @@ export class FormatECodec {
             const edges = omit
                 ? graph.edges.map(e => ({ ...e, attributes: stripEdgeProvenance(e.attributes) }))
                 : graph.edges;
+            // CR-SM-332: dieselbe Zusicherung an der Kante — ihr Inline-Block steht auf derselben Zeile.
+            for (const e of edges) {
+                for (const [k, v] of Object.entries(e.attributes)) {
+                    if (typeof v !== 'object') {
+                        assertSingleLine(`edge "${e.sourceId} -${e.edgeType}-> ${e.targetId}"`, `attribute "${k}"`, v);
+                    }
+                }
+            }
             lines.push(...this.serializeEdges(edges));
         }
         return lines.join('\n');
@@ -197,9 +270,17 @@ export class FormatECodec {
     // Private
     // ---------------------------------------------------------------------------
     parseNodeLine(line, nodeType, declared, ops, errors) {
-        const opChar = OP_PREFIX[line[0]] ? line[0] : '+';
-        const rest = OP_PREFIX[line[0]] ? line.slice(1).trim() : line.trim();
-        const action = OP_PREFIX[opChar] ?? 'add';
+        // CR-SM-332: das Operator-Praefix ist PFLICHT. Vorher war es optional ("kein Praefix =
+        // add"), womit JEDE Textzeile eine gueltige Knotenzeile war — genau der Weg, auf dem eine
+        // uebergelaufene Beschreibung zum Phantom-Knoten wurde. Ein Praefix zu verlangen kostet
+        // nichts (jeder Erzeuger schreibt es) und schliesst die Klasse.
+        const action = OP_PREFIX[line[0]];
+        if (!action) {
+            errors.push(`Node line without an operator prefix (+ - ~ !): "${line}" — eine Zeile ohne Operator `
+                + `ist keine Knotenzeile. Haeufigste Ursache: eine Beschreibung mit Zeilenumbruch.`);
+            return;
+        }
+        const rest = line.slice(1).trim();
         // Extract inline attributes
         let mainPart = rest;
         let inlineAttrs;
@@ -216,6 +297,14 @@ export class FormatECodec {
             errors.push(`Node line without a uid: "${line}"`);
             return;
         }
+        // CR-SM-332: die uid war "alles vor dem Pipe", Leerzeichen eingeschlossen — der zweite Teil
+        // desselben Einfallstors. Der (entfernte) contracts-Parser verlangte hier `\S+?` und haette
+        // den Fall gefangen; die Strenge wandert mit ihm hierher.
+        if (/\s/.test(uid)) {
+            errors.push(`Uid contains whitespace: "${uid}" — uids sind zusammenhaengend. Eine uebergelaufene `
+                + `Beschreibungszeile sieht genau so aus.`);
+            return;
+        }
         // CR-SM-217: with `TYPE-slug` as the family canon, the prefix restores the
         // redundancy CR-SM-216 removed — for free, since `REQ-safety` costs fewer tokens
         // than `REQ-safety.REQ`. A node under the wrong section is caught here. Uids with
@@ -356,7 +445,7 @@ export class FormatECodec {
                 entries.push({ sourceId: edge.sourceId, edgeType: edge.edgeType, targets: [edge.targetId], attrs });
                 continue;
             }
-            const key = `${edge.sourceId}${edge.edgeType}`;
+            const key = `${edge.sourceId}\0${edge.edgeType}`;
             const group = groups.get(key);
             if (group) {
                 group.targets.push(edge.targetId);
@@ -367,7 +456,6 @@ export class FormatECodec {
                 entries.push(entry);
             }
         }
-        const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
         for (const entry of entries)
             entry.targets.sort(cmp);
         entries.sort((a, b) => cmp(a.sourceId, b.sourceId)
@@ -387,18 +475,71 @@ export class FormatECodec {
      * contains no comma. No edge in the SE ontology carries a structured attribute today; if one
      * ever does, the inline block is the thing to replace, not this escape.
      */
-    serializeAttrs(attrs) {
-        const entries = Object.entries(attrs).filter(([, v]) => v != null && v !== '' && typeof v !== 'object');
-        if (entries.length === 0)
-            return '';
-        const pairs = entries.map(([k, v]) => `${k}:${String(v)}`);
-        return ` [${pairs.join(',')}]`;
+    /**
+     * CR-SM-332: EIN Kriterium entscheidet, ob ein Attribut inline oder auf eine `@key`-Zeile
+     * geht — naemlich, ob sein Wert den Inline-Block brechen wuerde.
+     *
+     * Vorher entschied der TYP: `typeof v === 'object'` ging auf die Folgezeile, alles andere
+     * inline. Damit blieb eine Luecke derselben Klasse wie der Zeilenumbruch offen: ein STRING
+     * mit Komma oder Klammer ("a, b" oder "f(x)") wurde inline geschrieben, und
+     * `parseInlineAttrs` splittet auf Kommas — der Wert kam zerteilt oder gar nicht zurueck.
+     * Still, wie immer bei dieser Klasse. graphcodes Fork hatte genau dafuer bereits
+     * `UNSAFE_ATTR_RE`; die Regel wandert hierher, wo der einzige Codec steht.
+     *
+     * Schluessel aufsteigend nach Code-Einheiten, nicht `localeCompare` — dieselbe Begruendung
+     * wie bei `serializeEdges`: eine Sortierung, die von der Locale abhaengt, ist nicht
+     * deterministisch.
+     */
+    nodeAttrParts(attrs) {
+        const entries = Object.entries(attrs)
+            .filter(([, v]) => v != null && v !== '')
+            .sort(([a], [b]) => cmp(a, b))
+            .map(([k, v]) => [k, typeof v === 'object' ? JSON.stringify(v) : String(v)]);
+        const safe = entries.filter(([, v]) => !UNSAFE_INLINE_RE.test(v));
+        const unsafe = entries.filter(([, v]) => UNSAFE_INLINE_RE.test(v));
+        return {
+            inline: safe.length > 0 ? ` [${safe.map(([k, v]) => `${k}:${v}`).join(',')}]` : '',
+            follow: unsafe.map(([k, v]) => `@${k} ${v}`),
+        };
     }
-    /** CR-GC-334: object/array attributes as `@key {json}` lines below the node entry. */
-    structuredAttrLines(attrs) {
-        return Object.entries(attrs)
-            .filter(([, v]) => v != null && typeof v === 'object')
-            .map(([k, v]) => `@${k} ${JSON.stringify(v)}`);
+    /**
+     * CR-SM-332 (aus graphcodes Fork uebernommen, CR-GC-200/CR-GC-531): Knotentypen gegen die
+     * Ontologie, Kantentypen gegen die Ontologie, doppelte uids, aufloesbare Endpunkte.
+     * Paar-Legalitaet gehoert NICHT hierher — das ist R-18, dort wo Daten in den Speicher
+     * gehen.
+     */
+    validate(graph, resolveType) {
+        const errors = [];
+        const declaredTypes = new Map(graph.nodes.map(n => [n.uid, n.type]));
+        const typeOf = (uid) => declaredTypes.get(uid) ?? resolveType?.(uid);
+        // Doppelte uids: die Map oben dedupliziert still, zwei Knoten mit derselben uid faellen
+        // sonst zu einem zusammen und die Kollision bleibt ungesehen (CR-GC-200).
+        const counts = new Map();
+        for (const node of graph.nodes)
+            counts.set(node.uid, (counts.get(node.uid) ?? 0) + 1);
+        for (const [uid, count] of counts) {
+            if (count > 1)
+                errors.push(`Duplicate node uid "${uid}" (${count} nodes share it)`);
+        }
+        for (const node of graph.nodes) {
+            if (!this.validNodeTypes.has(node.type)) {
+                errors.push(`Unknown node type "${node.type}" for node "${node.uid}"`);
+            }
+        }
+        for (const edge of graph.edges) {
+            if (!this.ontology.edgeTypes[edge.edgeType]) {
+                errors.push(`Unknown edge type "${edge.edgeType}" for edge "${edge.sourceId}" → "${edge.targetId}"`);
+                continue;
+            }
+            if (!typeOf(edge.sourceId)) {
+                errors.push(`Edge references unknown source node "${edge.sourceId}"`);
+                continue;
+            }
+            if (!typeOf(edge.targetId)) {
+                errors.push(`Edge references unknown target node "${edge.targetId}"`);
+            }
+        }
+        return { valid: errors.length === 0, errors };
     }
     /** Inline block for an EDGE — structured values stringified, see `serializeAttrs`. */
     serializeEdgeAttrs(attrs) {

package/dist/graph-service.js

@@ -8,6 +8,7 @@ import { isValidTrace, tracePatternsOf } from './types.js';
 import { FormatECodec } from './format-e-codec.js';
 import { DefaultRuleEngine } from './rule-engine.js';
 import { InMemoryAuditLog } from './audit.js';
+import { normalizeReqKinds } from '@sigloch/contracts/se';
 import { updateEdge, mergeNodes } from './edge-ops.js';
 /**
  * CR-SM-216: a display name for a typed node, derived from the uid's *shape* only.
@@ -489,10 +490,10 @@ export class GraphService {
             // Hoist top-level fields
             if (element.attributes) {
                 if (element.attributes.kinds != null) {
-                    const raw = String(element.attributes.kinds);
-                    element.kinds = raw.includes(',')
-                        ? raw.split(',').map((s) => s.trim())
-                        : [raw.trim()];
+                    // CR-SM-332: `normalizeReqKinds` statt einer zweiten, handgeschriebenen Fassung
+                    // (`String(raw).includes(',') ? split : [raw]`). Dieselbe Regel, ein Ort — die
+                    // Funktion liegt bei den Schemata, die sie fuettert.
+                    element.kinds = [...normalizeReqKinds(element.attributes.kinds)];
                     delete element.attributes.kinds;
                 }
                 if (element.attributes.asil != null) {
@@ -534,10 +535,8 @@ export class GraphService {
                 // Hoist top-level fields
                 if (element.attributes) {
                     if (element.attributes.kinds != null) {
-                        const raw = String(element.attributes.kinds);
-                        element.kinds = raw.includes(',')
-                            ? raw.split(',').map((s) => s.trim())
-                            : [raw.trim()];
+                        // CR-SM-332: dieselbe eine Regel wie im Anlege-Pfad oben.
+                        element.kinds = [...normalizeReqKinds(element.attributes.kinds)];
                         delete element.attributes.kinds;
                     }
                     if (element.attributes.asil != null) {

package/dist/se-descriptor.js

@@ -9,7 +9,7 @@
  *   - Graph (nodes/edges)        ⟷  OntologyGraph (elements/traces)
  *   - RuleViolation (ruleId/…)   ⟷  contracts RuleViolation (rule_id/…)
  */
-import { ElementType, TraceType, TRACE_PATTERNS, V3_RULES, MT_RULES, UC_RULES, FC_RULES, SC_RULES, CR_RULES, AO_RULES, FM_RULES, VIEW_RULES, AF_RULES, ONTOLOGY_VERSION, DEFAULT_METRIC_POLICY, } from '@sigloch/contracts/se';
+import { ElementType, TraceType, TRACE_PATTERNS, V3_RULES, MT_RULES, UC_RULES, FC_RULES, SC_RULES, CR_RULES, AO_RULES, FM_RULES, VIEW_RULES, AF_RULES, ONTOLOGY_VERSION, DEFAULT_METRIC_POLICY, normalizeReqKinds, } from '@sigloch/contracts/se';
 /**
  * Project an ontology-agnostic Graph (nodes/edges) onto the SE OntologyGraph
  * (elements/traces) that contracts/se rules evaluate against. Type-specific
@@ -32,7 +32,15 @@ export function projectToOntologyGraph(graph) {
         created_at: n.createdAt ?? '',
         updated_at: n.updatedAt,
         method: n.attributes?.method,
-        kinds: n.attributes?.kinds,
+        // CR-SM-332 (ITEM-2026-183): `kinds` wird NORMALISIERT, nicht gecastet. Der Cast war die
+        // dritte Fassung derselben Wahrheit: der (entfernte) contracts-Parser normalisierte beim
+        // Lesen, GraphService.hoist tut es von Hand, und HIER kam ein ueber Format-E eingetragenes
+        // `@kinds non-functional` als roher STRING bei den Regeln an, wo eine Liste erwartet wird —
+        // CR-SM-320 auf diesem Pfad wieder offen. `undefined` bleibt `undefined`: eine leere Liste
+        // ist eine andere Aussage als "nicht gesetzt".
+        kinds: n.attributes?.kinds === undefined
+            ? undefined
+            : normalizeReqKinds(n.attributes.kinds),
         attributes: n.attributes,
     }));
     const traces = graph.edges.map((e) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/graph-api-core",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",