@sigloch/graph-api-core 0.4.0

package/dist/testing/storage-contract-tests.js

@@ -0,0 +1,113 @@
+/**
+ * Contract test suite for StorageAdapter implementations.
+ * Every adapter (Neo4j, SQLite, Memory, File) must pass these tests.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+const SCOPE = { workspaceId: 'test', systemId: 'test' };
+function makeNode(uid, type = 'ACT') {
+    return {
+        uid,
+        type,
+        name: uid.split('.')[0],
+        description: `Test node ${uid}`,
+        attributes: {},
+        createdAt: new Date().toISOString(),
+    };
+}
+function makeEdge(sourceId, targetId, edgeType = 'FLOWS_TO') {
+    return { sourceId, targetId, edgeType, attributes: {} };
+}
+export function runStorageContractTests(factory) {
+    describe('StorageAdapter Contract', () => {
+        let adapter;
+        beforeEach(async () => {
+            adapter = await factory();
+            await adapter.initialize();
+        });
+        afterEach(async () => {
+            await adapter.shutdown();
+        });
+        it('starts with empty graph', async () => {
+            const graph = await adapter.loadGraph(SCOPE);
+            expect(graph.nodes).toHaveLength(0);
+            expect(graph.edges).toHaveLength(0);
+        });
+        it('saves and loads nodes', async () => {
+            const node = makeNode('TestActor.ACT.01');
+            await adapter.saveNodes([node]);
+            const graph = await adapter.loadGraph(SCOPE);
+            expect(graph.nodes).toHaveLength(1);
+            expect(graph.nodes[0].uid).toBe('TestActor.ACT.01');
+        });
+        it('saves and loads edges', async () => {
+            const n1 = makeNode('Source.ACT.01');
+            const n2 = makeNode('Target.ACT.02');
+            await adapter.saveNodes([n1, n2]);
+            await adapter.saveEdges([makeEdge('Source.ACT.01', 'Target.ACT.02')]);
+            const graph = await adapter.loadGraph(SCOPE);
+            expect(graph.edges).toHaveLength(1);
+            expect(graph.edges[0].sourceId).toBe('Source.ACT.01');
+        });
+        it('deletes nodes and cascades edges', async () => {
+            const n1 = makeNode('A.ACT.01');
+            const n2 = makeNode('B.ACT.02');
+            await adapter.saveNodes([n1, n2]);
+            await adapter.saveEdges([makeEdge('A.ACT.01', 'B.ACT.02')]);
+            await adapter.deleteNodes(['A.ACT.01']);
+            const graph = await adapter.loadGraph(SCOPE);
+            expect(graph.nodes).toHaveLength(1);
+            expect(graph.edges).toHaveLength(0);
+        });
+        it('deletes edges', async () => {
+            const n1 = makeNode('A.ACT.01');
+            const n2 = makeNode('B.ACT.02');
+            await adapter.saveNodes([n1, n2]);
+            await adapter.saveEdges([makeEdge('A.ACT.01', 'B.ACT.02')]);
+            await adapter.deleteEdges([{ sourceId: 'A.ACT.01', targetId: 'B.ACT.02', edgeType: 'FLOWS_TO' }]);
+            const graph = await adapter.loadGraph(SCOPE);
+            expect(graph.nodes).toHaveLength(2);
+            expect(graph.edges).toHaveLength(0);
+        });
+        it('getNode returns null for missing', async () => {
+            const result = await adapter.getNode('DoesNotExist.ACT.99');
+            expect(result).toBeNull();
+        });
+        it('getNode returns existing', async () => {
+            await adapter.saveNodes([makeNode('Found.ACT.01')]);
+            const result = await adapter.getNode('Found.ACT.01');
+            expect(result).not.toBeNull();
+            expect(result.uid).toBe('Found.ACT.01');
+        });
+        it('getSubgraph returns correct depth', async () => {
+            const nodes = [makeNode('Root.ACT.01'), makeNode('Child.ACT.02'), makeNode('Grand.ACT.03')];
+            await adapter.saveNodes(nodes);
+            await adapter.saveEdges([
+                makeEdge('Root.ACT.01', 'Child.ACT.02'),
+                makeEdge('Child.ACT.02', 'Grand.ACT.03'),
+            ]);
+            const depth1 = await adapter.getSubgraph('Root.ACT.01', 1);
+            expect(depth1.nodes).toHaveLength(2);
+            const depth2 = await adapter.getSubgraph('Root.ACT.01', 2);
+            expect(depth2.nodes).toHaveLength(3);
+        });
+        it('stats returns correct counts', async () => {
+            await adapter.saveNodes([makeNode('A.ACT.01'), makeNode('B.ACT.02')]);
+            await adapter.saveEdges([makeEdge('A.ACT.01', 'B.ACT.02')]);
+            const stats = await adapter.stats();
+            expect(stats.nodeCount).toBe(2);
+            expect(stats.edgeCount).toBe(1);
+        });
+        it('upserts nodes (save twice)', async () => {
+            const node = makeNode('Upsert.ACT.01');
+            await adapter.saveNodes([node]);
+            const updated = { ...node, description: 'Updated' };
+            await adapter.saveNodes([updated]);
+            const graph = await adapter.loadGraph(SCOPE);
+            expect(graph.nodes).toHaveLength(1);
+            expect(graph.nodes[0].description).toBe('Updated');
+        });
+        it('isHealthy returns true', async () => {
+            expect(await adapter.isHealthy()).toBe(true);
+        });
+    });
+}

package/dist/transport-adapter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * TransportAdapter interface — binds GraphService to HTTP/WS/MCP/CLI frameworks.
+ */
+import type { GraphService } from './graph-service.js';
+export interface TransportConfig {
+    port?: number;
+    host?: string;
+}
+export interface TransportAdapter {
+    mount(service: GraphService, config: TransportConfig): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/transport-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Core types for graph-api-core — ontology-agnostic.
+ * Domains register their node/edge types via OntologyDescriptor.
+ */
+export interface GraphNode {
+    uid: string;
+    type: string;
+    name: string;
+    description?: string;
+    attributes: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface GraphEdge {
+    sourceId: string;
+    targetId: string;
+    edgeType: string;
+    attributes: Record<string, unknown>;
+}
+export interface Graph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export interface NodeTypeDescriptor {
+    label: string;
+    requiredAttrs: string[];
+}
+export interface EdgeTypeDescriptor {
+    /** Arrow aliases for Format E parsing (e.g. ['compose', 'cp']). */
+    arrows: string[];
+    /** Valid source→target node type pairs. */
+    validPairs: [string, string][];
+}
+export interface TracePattern {
+    source: string;
+    target: string;
+    type: string;
+    /** Optional label refinement (e.g. MS→MS relation 'depends-on'). */
+    label?: string;
+}
+export interface OntologyDescriptor {
+    name: string;
+    version: string;
+    nodeTypes: Record<string, NodeTypeDescriptor>;
+    edgeTypes: Record<string, EdgeTypeDescriptor>;
+    /**
+     * Authoritative trace-legality patterns (CR-GC-247). The ONE source the engine
+     * validates edges against — supersedes per-edgeType `validPairs`, which is now
+     * only a menu/arrow enumeration. Omit to derive patterns from validPairs
+     * (foreign ontologies that declare only pairs); see {@link tracePatternsOf}.
+     */
+    patterns?: TracePattern[];
+    /** Domain-specific rules. */
+    rules?: Rule[];
+}
+interface Rule {
+    id: string;
+    name: string;
+    severity: 'error' | 'warning' | 'info';
+    evaluate: (graph: Graph) => RuleViolation[];
+}
+interface RuleViolation {
+    ruleId: string;
+    ruleName: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    elementId?: string;
+}
+export interface GraphScope {
+    workspaceId: string;
+    systemId: string;
+}
+export interface GraphQuery {
+    type: 'elements' | 'edges' | 'subgraph' | 'view';
+    filter?: Record<string, unknown>;
+    view?: string;
+    root?: string;
+    depth?: number;
+    format?: 'json' | 'format-e';
+}
+export interface MutationResult {
+    applied: number;
+    rejected: number;
+    violations: RuleViolation[];
+    version: number;
+    auditId: string;
+}
+export interface BatchResult {
+    results: MutationResult[];
+    totalApplied: number;
+    totalRejected: number;
+}
+export interface HealthStatus {
+    status: 'ok' | 'degraded' | 'down';
+    storage: string;
+    ontologyName: string;
+    ontologyVersion: string;
+    elementCount: number;
+    edgeCount: number;
+    violationCount: number;
+}
+export interface FormatEOperation {
+    type: 'add_node' | 'remove_node' | 'update_node' | 'add_edge' | 'remove_edge' | 'update_edge' | 'strict_add_node' | 'strict_add_edge' | 'merge_nodes';
+    /** Node uid or edge key (source->target). */
+    semanticId: string;
+    description?: string;
+    attributes?: Record<string, string>;
+    sourceId?: string;
+    targetId?: string;
+    edgeType?: string;
+    /** Merge operation: source node IDs to merge. */
+    sourceIds?: string[];
+    /** update_edge: identity is sourceId/targetId/edgeType above; this is the change (CR-198). */
+    set?: {
+        edgeType?: string;
+        flip?: boolean;
+        attributes?: Record<string, string>;
+    };
+}
+export interface FormatEDiff {
+    operations: FormatEOperation[];
+    errors: string[];
+}
+/**
+ * Structural trace-legality check. Ontology-agnostic: matches a trace against
+ * TracePattern[] with '*' wildcards on source/target. Both graph-service and
+ * format-e-codec route every check through this — validPairs is no longer a
+ * parallel re-implementation.
+ *
+ * A pattern's `label` is descriptive metadata (e.g. MS→MS relation 'depends-on'),
+ * NOT a gate: label is trace data that isn't uniformly carried through the
+ * Graph/codec pipeline, and the legality this replaces (validPairs) never keyed on
+ * it. Enforcing label is a deliberate tightening (needs codec label round-tripping),
+ * out of scope for the centralization.
+ */
+export declare function isValidTrace(trace: {
+    source: string;
+    target: string;
+    type: string;
+}, patterns: TracePattern[]): boolean;
+/**
+ * The patterns a descriptor validates against: explicit `patterns` (SSOT) if set,
+ * else derived from each edgeType's `validPairs` (menu → legality) so foreign
+ * ontologies that declare only pairs keep working.
+ */
+export declare function tracePatternsOf(ontology: OntologyDescriptor): TracePattern[];
+export {};

package/dist/types.js

@@ -0,0 +1,39 @@
+/**
+ * Core types for graph-api-core — ontology-agnostic.
+ * Domains register their node/edge types via OntologyDescriptor.
+ */
+// ---------------------------------------------------------------------------
+// Trace legality — the ONE checker (CR-GC-247)
+// ---------------------------------------------------------------------------
+/**
+ * Structural trace-legality check. Ontology-agnostic: matches a trace against
+ * TracePattern[] with '*' wildcards on source/target. Both graph-service and
+ * format-e-codec route every check through this — validPairs is no longer a
+ * parallel re-implementation.
+ *
+ * A pattern's `label` is descriptive metadata (e.g. MS→MS relation 'depends-on'),
+ * NOT a gate: label is trace data that isn't uniformly carried through the
+ * Graph/codec pipeline, and the legality this replaces (validPairs) never keyed on
+ * it. Enforcing label is a deliberate tightening (needs codec label round-tripping),
+ * out of scope for the centralization.
+ */
+export function isValidTrace(trace, patterns) {
+    return patterns.some((p) => (p.source === '*' || p.source === trace.source) &&
+        (p.target === '*' || p.target === trace.target) &&
+        p.type === trace.type);
+}
+/**
+ * The patterns a descriptor validates against: explicit `patterns` (SSOT) if set,
+ * else derived from each edgeType's `validPairs` (menu → legality) so foreign
+ * ontologies that declare only pairs keep working.
+ */
+export function tracePatternsOf(ontology) {
+    if (ontology.patterns)
+        return ontology.patterns;
+    const derived = [];
+    for (const [type, desc] of Object.entries(ontology.edgeTypes)) {
+        for (const [source, target] of desc.validPairs)
+            derived.push({ source, target, type });
+    }
+    return derived;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@sigloch/graph-api-core",
+  "version": "0.4.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "test-fixtures"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./browser": "./dist/browser.js",
+    "./testing": "./dist/testing/index.js",
+    "./test-fixtures": "./dist/test-fixtures.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "dependencies": {
+    "@sigloch/contracts": "^0.7.0",
+    "zod": "^4.3.6"
+  },
+  "license": "MIT",
+  "description": "Framework-agnostic graph engine core — ontology-typed nodes/traces, rule evaluation, views",
+  "author": "sigloch-consulting",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andreassigloch/sigloch-modules.git",
+    "directory": "packages/graph-api-core"
+  },
+  "homepage": "https://github.com/andreassigloch/sigloch-modules#readme",
+  "bugs": {
+    "url": "https://github.com/andreassigloch/sigloch-modules/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/test-fixtures/cr-007-features.format-e.md

@@ -0,0 +1,22 @@
+# Format-E Test Fixture · CR-007 features
+
+Exercises the reserved inline attributes from CR-007:
+- Nodes: `notes`
+- Edges: `cardinality`, `constraint`, `notes`
+
+Uses the minimal `TEST_ONTOLOGY` shipped from `@sigloch/graph-api-core/test-fixtures`.
+
+```format-e
+## Nodes
++ Mower.PR.01|Riding mower R15 [notes:Phase-2-Vertical-Slice-Wurzel]
++ Engine.C.01|Combustion engine [power:gas]
++ Gearbox.C.02|Mowing-deck gearbox family [kind:family,notes:drei Varianten geplant]
++ DFMEA-Engine-001.FR.01|Not-Stop-Funktion am Motor [external_id:DFMEA-Engine-001]
++ EmergencyBrake.CTRL.01|Mechanische Bremse Stillstandszeit max 5 sec
+
+## Edges
++ Mower.PR.01 -compose-> Engine.C.01 [cardinality:1..1]
++ Mower.PR.01 -compose-> Gearbox.C.02 [cardinality:1..n,constraint:mindestens eine Variante je Schnittbreite]
++ Engine.C.01 -addressed_by-> DFMEA-Engine-001.FR.01 [cardinality:1..n,notes:DFMEA-Hotspot]
++ DFMEA-Engine-001.FR.01 -addressed_by-> EmergencyBrake.CTRL.01 [cardinality:1..1,constraint:Stillstandszeit <= 5 sec]
+```

package/test-fixtures/empty.format-e.md

@@ -0,0 +1,6 @@
+# Format-E Test Fixture · empty
+
+Empty diff. Codec must accept and yield zero operations.
+
+```format-e
+```

package/test-fixtures/rasentraktor.format-e.md

@@ -0,0 +1,46 @@
+# Format-E Test Fixture · Rasentraktor R15 (Subset)
+
+Vertical-Slice-Auszug aus dem ontoagent-Trockenlauf v0.3 ("Rasentraktor R15 /
+Mähwerk-Getriebe"). Vollständige Domäne siehe ontoagent
+`docs/examples/format-e-rasentraktor.md`; diese Fixture ist die kompakte,
+sigloch-weit nutzbare Variante für CI-Smokes.
+
+Validiert gegen `TEST_ONTOLOGY` aus `@sigloch/graph-api-core/test-fixtures`.
+
+```format-e
+## Nodes
++ Konstruktion.OU.01|Konstruktion
++ Tooling.OU.02|Tooling
++ DesignLead.R.01|Design Lead
++ Tooling.R.02|Tooling
++ R15.PR.01|Rasentraktor R15 [code:R15]
++ R15-1000.VAR.01|R15 mit 1000 mm Schnittbreite [attribute_key:Schnittbreite,attribute_value:1000mm]
++ R15-1500.VAR.02|R15 mit 1500 mm Schnittbreite [attribute_key:Schnittbreite,attribute_value:1500mm]
++ MaehwerkGetriebe.C.01|Maehwerk-Getriebe Familie [kind:family]
++ Getriebe-1000.C.02|Getriebe 1000 [kind:variant,part_no:MG-1000]
++ Getriebe-1500.C.03|Getriebe 1500 [kind:variant,part_no:MG-1500]
++ UnterschiedlicheMaehbreiten.F.01|Unterschiedliche Maehbreiten [customer_priority:hoch]
++ DFMEA-MG-001.FR.01|Not-Stop-Funktion [external_id:DFMEA-MG-001,status:verifiziert]
++ MechBremse.CTRL.01|Mechanische Bremse Stillstandszeit max 5 sec
++ Stillstandszeitmessung.TC.01|Stillstandszeit-Messung nach Not-Aus [criterion:t_stop <= 5 sec]
++ WerkzeugSetGehaeuse.TL.01|Werkzeug-Set Gehaeuse Druckguss [material:Aluminium-Druckguss]
++ M3.MT.01|GO Milestone [sequence_no:3]
++ PDM.SL.01|PDM-System [type:PLM]
+
+## Edges
++ R15.PR.01 -compose-> MaehwerkGetriebe.C.01 [cardinality:1..1]
++ MaehwerkGetriebe.C.01 -compose-> Getriebe-1000.C.02 [cardinality:1..n,constraint:eine Variante je Schnittbreite]
++ MaehwerkGetriebe.C.01 -compose-> Getriebe-1500.C.03 [cardinality:1..n]
++ R15.PR.01 -has_variant-> R15-1000.VAR.01 [cardinality:1..n]
++ R15.PR.01 -has_variant-> R15-1500.VAR.02 [cardinality:1..n]
++ UnterschiedlicheMaehbreiten.F.01 -realized_by-> MaehwerkGetriebe.C.01 [cardinality:1..n]
++ MaehwerkGetriebe.C.01 -addressed_by-> DFMEA-MG-001.FR.01 [cardinality:1..n]
++ DFMEA-MG-001.FR.01 -addressed_by-> MechBremse.CTRL.01 [cardinality:1..1,constraint:Stillstandszeit <= 5 sec]
++ MechBremse.CTRL.01 -verified_by-> Stillstandszeitmessung.TC.01 [cardinality:1..1]
++ Tooling.OU.02 -responsible_for-> WerkzeugSetGehaeuse.TL.01 [cardinality:1..1]
++ Konstruktion.OU.01 -responsible_for-> MaehwerkGetriebe.C.01 [cardinality:1..1]
++ DesignLead.R.01 -within-> Konstruktion.OU.01 [cardinality:1..1]
++ Tooling.R.02 -within-> Tooling.OU.02 [cardinality:1..1]
++ M3.MT.01 -requires_document_of_type-> DFMEA-MG-001.FR.01 [cardinality:1..n,notes:GO-Gate verlangt finalisierte D-FMEA]
++ MaehwerkGetriebe.C.01 -stored_in-> PDM.SL.01 [cardinality:1..1]
+```