@sigloch/graph-api-core 0.4.0

package/dist/format-e-codec.js

@@ -0,0 +1,296 @@
+/**
+ * FormatECodec — ontology-agnostic Format E parser/serializer.
+ * Domain-specific node types, edge types, and arrows come from OntologyDescriptor.
+ */
+import { isValidTrace, tracePatternsOf } from './types.js';
+// ---------------------------------------------------------------------------
+// Regex patterns
+// ---------------------------------------------------------------------------
+const OP_PREFIX = {
+    '+': 'add',
+    '-': 'remove',
+    '~': 'update',
+    '!': 'strict_add',
+};
+const ATTR_RE = /^\s*@(\w+)\s+(.+)$/;
+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 = /\[([^\]]+)\]$/;
+export class FormatECodec {
+    ontology;
+    edgeArrowToType;
+    validNodeTypes;
+    /** Trace-legality patterns (CR-GC-247) — the SSOT the parser validates edges against. */
+    patterns;
+    constructor(ontology) {
+        this.ontology = ontology;
+        // Build arrow → edge type lookup
+        this.edgeArrowToType = new Map();
+        for (const [edgeType, desc] of Object.entries(ontology.edgeTypes)) {
+            for (const arrow of desc.arrows) {
+                this.edgeArrowToType.set(arrow.toLowerCase(), edgeType);
+            }
+        }
+        // Valid node type abbreviations
+        this.validNodeTypes = new Set(Object.keys(ontology.nodeTypes));
+        // Meta-model legality: descriptor.patterns (or derived from validPairs).
+        this.patterns = tracePatternsOf(ontology);
+    }
+    /** Extract a ```format-e block from LLM output. Returns null if not found. */
+    extractFromLlm(llmOutput) {
+        const m = FORMAT_E_FENCE.exec(llmOutput);
+        return m ? m[1].trim() : null;
+    }
+    /** Parse Format E text into validated operations. */
+    parse(input) {
+        const operations = [];
+        const errors = [];
+        let section = null;
+        for (const rawLine of input.split('\n')) {
+            const line = rawLine.trim();
+            if (!line || line.startsWith('//') || line.startsWith('#!'))
+                continue;
+            // @attribute lines attach to last node operation
+            const attrMatch = ATTR_RE.exec(line);
+            if (attrMatch) {
+                const lastOp = operations.length > 0 ? operations[operations.length - 1] : null;
+                if (lastOp && (lastOp.type === 'add_node' || lastOp.type === 'update_node' || lastOp.type === 'strict_add_node')) {
+                    if (!lastOp.attributes)
+                        lastOp.attributes = {};
+                    lastOp.attributes[attrMatch[1]] = attrMatch[2].trim();
+                }
+                else {
+                    errors.push(`@attribute line without preceding node: "${line}"`);
+                }
+                continue;
+            }
+            // Section headers
+            if (/^##\s*nodes?\s*$/i.test(line)) {
+                section = 'nodes';
+                continue;
+            }
+            if (/^##\s*edges?\s*$/i.test(line)) {
+                section = 'edges';
+                continue;
+            }
+            if (/^##\s*merges?\s*$/i.test(line)) {
+                section = 'merges';
+                continue;
+            }
+            if (line.startsWith('#'))
+                continue;
+            // Merge operations
+            const mergeMatch = MERGE_RE.exec(line);
+            if (mergeMatch || section === 'merges') {
+                if (mergeMatch) {
+                    this.parseMerge(mergeMatch[1], operations, errors);
+                }
+                else {
+                    errors.push(`Invalid merge line: "${line}"`);
+                }
+                continue;
+            }
+            // Edge: detect by arrow pattern -xxx->, but only in the structural part
+            // (before the description pipe). Node descriptions may legitimately contain
+            // '->' (e.g. "FUNC->FUNC compose"); the arrow lives before any '|', edges
+            // carry no pipe — so splitting on '|' cleanly disambiguates (CR-GC-247).
+            if (line.split('|', 1)[0].includes('->')) {
+                this.parseEdgeLine(line, operations, errors);
+                continue;
+            }
+            // Node
+            if (section === 'nodes' || this.looksLikeNode(line)) {
+                this.parseNodeLine(line, operations, errors);
+                continue;
+            }
+            if (line.length > 0)
+                errors.push(`Unrecognized line: "${line}"`);
+        }
+        return { operations, errors };
+    }
+    /** Serialize a Graph to Format E text. */
+    serialize(graph) {
+        const lines = [];
+        if (graph.nodes.length > 0) {
+            lines.push('## Nodes');
+            for (const node of graph.nodes) {
+                const descr = node.description ? `|${node.description}` : '';
+                const attrs = this.serializeAttrs(node.attributes);
+                lines.push(`+ ${node.uid}${descr}${attrs}`);
+            }
+        }
+        if (graph.edges.length > 0) {
+            lines.push('');
+            lines.push('## Edges');
+            for (const edge of graph.edges) {
+                const arrow = this.edgeTypeToArrow(edge.edgeType);
+                const attrs = this.serializeAttrs(edge.attributes);
+                lines.push(`+ ${edge.sourceId} -${arrow}-> ${edge.targetId}${attrs}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    looksLikeNode(line) {
+        const stripped = line.replace(/^[+\-~!]\s*/, '');
+        const dotParts = stripped.split('.');
+        return dotParts.length >= 2 && this.validNodeTypes.has(dotParts[dotParts.length - 2] ?? '');
+    }
+    parseNodeLine(line, 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';
+        // Extract inline attributes
+        let mainPart = rest;
+        let inlineAttrs;
+        const attrMatch = INLINE_ATTRS_RE.exec(rest);
+        if (attrMatch) {
+            mainPart = rest.slice(0, attrMatch.index).trim();
+            inlineAttrs = this.parseInlineAttrs(attrMatch[1]);
+        }
+        // Split uid|description
+        const pipeIdx = mainPart.indexOf('|');
+        const uid = pipeIdx >= 0 ? mainPart.slice(0, pipeIdx).trim() : mainPart.trim();
+        const description = pipeIdx >= 0 ? mainPart.slice(pipeIdx + 1).trim() : undefined;
+        // Validate node type from uid
+        const nodeType = this.extractNodeType(uid);
+        if (!nodeType) {
+            errors.push(`Cannot extract node type from uid: "${uid}"`);
+            return;
+        }
+        if (!this.validNodeTypes.has(nodeType)) {
+            errors.push(`Unknown node type "${nodeType}" in: "${uid}"`);
+            return;
+        }
+        if (action === 'remove') {
+            ops.push({ type: 'remove_node', semanticId: uid });
+        }
+        else if (action === 'update') {
+            ops.push({ type: 'update_node', semanticId: uid, description, attributes: inlineAttrs });
+        }
+        else if (action === 'strict_add') {
+            ops.push({ type: 'strict_add_node', semanticId: uid, description, attributes: inlineAttrs });
+        }
+        else {
+            ops.push({ type: 'add_node', semanticId: uid, description, attributes: inlineAttrs });
+        }
+    }
+    parseEdgeLine(line, 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';
+        // Extract inline attributes from the line
+        let mainPart = rest;
+        let inlineAttrs;
+        const attrMatch = INLINE_ATTRS_RE.exec(rest);
+        if (attrMatch) {
+            mainPart = rest.slice(0, attrMatch.index).trim();
+            inlineAttrs = this.parseInlineAttrs(attrMatch[1]);
+        }
+        // Parse: sourceId -arrowType-> targetId[, targetId2, ...]
+        const arrowMatch = /^(\S+)\s+-(\w+)->\s+(.+)$/.exec(mainPart);
+        if (!arrowMatch) {
+            errors.push(`Invalid edge syntax: "${line}"`);
+            return;
+        }
+        const sourceId = arrowMatch[1];
+        const arrowType = arrowMatch[2].toLowerCase();
+        const targetsPart = arrowMatch[3];
+        // Resolve arrow → edge type
+        const edgeType = this.edgeArrowToType.get(arrowType);
+        if (!edgeType) {
+            errors.push(`Unknown edge arrow type "${arrowType}" in: "${line}"`);
+            return;
+        }
+        // Validate source node type
+        const srcType = this.extractNodeType(sourceId);
+        if (!srcType) {
+            errors.push(`Cannot extract node type from source: "${sourceId}"`);
+            return;
+        }
+        // Handle 1:N targets
+        const targets = targetsPart.split(',').map(t => t.trim()).filter(Boolean);
+        for (const targetId of targets) {
+            // Validate target node type
+            const tgtType = this.extractNodeType(targetId);
+            if (!tgtType) {
+                errors.push(`Cannot extract node type from target: "${targetId}"`);
+                continue;
+            }
+            // Meta-model validation (CR-GC-247: single checker, patterns SSOT — honors
+            // '*' wildcards, unlike the old per-edgeType validPairs set-membership).
+            if (!isValidTrace({ source: srcType, target: tgtType, type: edgeType }, this.patterns)) {
+                errors.push(`Meta-model violation: ${srcType} -${edgeType}-> ${tgtType} is not valid`);
+                continue;
+            }
+            const opType = action === 'remove'
+                ? 'remove_edge'
+                : action === 'strict_add'
+                    ? 'strict_add_edge'
+                    : 'add_edge';
+            const op = {
+                type: opType,
+                semanticId: `${sourceId}->${targetId}`,
+                sourceId,
+                targetId,
+                edgeType,
+            };
+            if (inlineAttrs)
+                op.attributes = inlineAttrs;
+            ops.push(op);
+        }
+    }
+    parseMerge(content, ops, errors) {
+        const parts = content.split('+').map(p => p.trim()).filter(Boolean);
+        if (parts.length < 2) {
+            errors.push(`Merge requires at least 2 nodes: "${content}"`);
+            return;
+        }
+        ops.push({
+            type: 'merge_nodes',
+            semanticId: `merge:${parts.join('+')}`,
+            sourceIds: parts,
+        });
+    }
+    extractNodeType(uid) {
+        const parts = uid.split('.');
+        // Format: Name.TYPE or Name.TYPE.Counter
+        if (parts.length >= 2) {
+            // Type is the last segment that matches a known type, or second-to-last
+            for (let i = parts.length - 1; i >= 1; i--) {
+                if (this.validNodeTypes.has(parts[i]))
+                    return parts[i];
+            }
+            // Fallback: second segment for 3-part IDs
+            if (parts.length >= 3)
+                return parts[parts.length - 2];
+            return parts[1];
+        }
+        return null;
+    }
+    parseInlineAttrs(raw) {
+        const attrs = {};
+        for (const pair of raw.split(',')) {
+            const colonIdx = pair.indexOf(':');
+            if (colonIdx > 0) {
+                attrs[pair.slice(0, colonIdx).trim()] = pair.slice(colonIdx + 1).trim();
+            }
+        }
+        return attrs;
+    }
+    serializeAttrs(attrs) {
+        const entries = Object.entries(attrs).filter(([, v]) => v != null && v !== '');
+        if (entries.length === 0)
+            return '';
+        const pairs = entries.map(([k, v]) => `${k}:${String(v)}`);
+        return ` [${pairs.join(',')}]`;
+    }
+    edgeTypeToArrow(edgeType) {
+        // Use first defined arrow alias
+        const desc = this.ontology.edgeTypes[edgeType];
+        return desc?.arrows[0] ?? edgeType.toLowerCase();
+    }
+}

package/dist/graph-service.d.ts

@@ -0,0 +1,37 @@
+import type { OntologyDescriptor, GraphQuery, MutationResult, BatchResult, HealthStatus, FormatEDiff, Graph, GraphNode, GraphScope } from './types.js';
+import type { StorageAdapter } from './storage-adapter.js';
+import type { RuleEngine, RuleViolation } from './rule-engine.js';
+import type { AuditLog } from './audit.js';
+import { FormatECodec } from './format-e-codec.js';
+export interface GraphServiceConfig {
+    ontology: OntologyDescriptor;
+    storage: StorageAdapter;
+    ruleEngine?: RuleEngine;
+    auditLog?: AuditLog;
+    scope?: GraphScope;
+}
+export declare class GraphService {
+    readonly ontology: OntologyDescriptor;
+    readonly codec: FormatECodec;
+    private readonly storage;
+    private readonly rules;
+    private readonly audit;
+    private readonly scope;
+    /** Trace-legality patterns (CR-GC-247) — the SSOT every edge validates against. */
+    private readonly patterns;
+    private version;
+    constructor(config: GraphServiceConfig);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    query(q: GraphQuery): Promise<Graph>;
+    getElement(uid: string): Promise<GraphNode | null>;
+    getSubgraph(root: string, depth?: number): Promise<Graph>;
+    mutate(diff: FormatEDiff, consumerId?: string): Promise<MutationResult>;
+    applyBatch(diffs: FormatEDiff[], consumerId?: string): Promise<BatchResult>;
+    validate(): Promise<RuleViolation[]>;
+    export(format?: 'format-e' | 'json'): Promise<string>;
+    health(): Promise<HealthStatus>;
+    private applyNodeCreate;
+    private applyNodeUpdate;
+    private validateAndApplyEdge;
+}