@sigloch/graph-api-core 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sigloch Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/audit.d.ts

@@ -0,0 +1,103 @@
+import type { FormatEDiff } from './types.js';
+import type { RuleViolation } from './rule-engine.js';
+import type { MutateCommand } from '@sigloch/contracts/harness';
+export interface AuditEntry {
+    id: string;
+    timestamp: string;
+    consumerId: string;
+    consumerType: 'frontend' | 'agent' | 'automation';
+    operation: 'mutate' | 'batch' | 'validate' | 'export';
+    diff?: FormatEDiff;
+    /**
+     * The mutate commands that produced this entry (CR-207, formerly the graphcode-
+     * local `GraphcodeAuditEntry.commands`). Optional: a `validate`/`export` entry
+     * carries none, and pre-CR-207 records predate the field. Replay-merge reads
+     * these in log order; without them replay is impossible.
+     */
+    commands?: MutateCommand[];
+    result: 'applied' | 'rejected' | 'partial';
+    violations?: RuleViolation[];
+    graphVersion: number;
+}
+export interface AuditLog {
+    record(entry: AuditEntry): Promise<void>;
+    query(filter: {
+        consumerId?: string;
+        since?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+}
+/**
+ * The durable operations-log surface: append/query (AuditLog) plus the event-
+ * sourcing primitives replay-merge and OCC build on — version continuity across
+ * sessions and compactions, and compaction itself. `compact()` writes a CHECKPOINT
+ * line that anchors the version so it is identical before and after; replay of the
+ * command batches after a fork point is a consumer concern (it needs the gate), so
+ * it is not on this interface — the log only guarantees the batches are durable and
+ * ordered.
+ */
+export interface OperationsLog extends AuditLog {
+    /** The compaction anchor: checkpoint version, or 0 on a never-compacted log. */
+    baseVersion(): number;
+    /** Highest known graph version — checkpoint anchor or max recorded entry version. */
+    latestVersion(): number;
+    /** Archive the active log and restart it anchored by a checkpoint line (version-safe). */
+    compact(reason?: string): {
+        archivedTo: string | null;
+        checkpointVersion: number;
+    };
+}
+export declare class InMemoryAuditLog implements AuditLog {
+    private entries;
+    record(entry: AuditEntry): Promise<void>;
+    query(filter: {
+        consumerId?: string;
+        since?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+}
+/** Auto-compaction size threshold (bytes). */
+export declare const DEFAULT_COMPACT_BYTES: number;
+/** Log filename inside the store dir — the log lives BESIDE the store it describes. */
+export declare const AUDIT_BASENAME = "audit.jsonl";
+/** Standard-layout location relative to the repo root (store dir = `.graphcode`). */
+export declare const AUDIT_FILE: string;
+export declare class FileOperationsLog implements OperationsLog {
+    private readonly path;
+    private readonly maxBytes;
+    /**
+     * `storeDir` = the directory of the store this log describes (same anchoring rule
+     * as the ownership lock: per store, never per repo).
+     */
+    constructor(storeDir: string, opts?: {
+        maxBytes?: number;
+    });
+    record(entry: AuditEntry): Promise<void>;
+    /** Mirrors InMemoryAuditLog semantics: `since` inclusive, `limit` = last N. */
+    query(filter: {
+        consumerId?: string;
+        since?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+    /** The compaction anchor: checkpoint version, or 0 on a never-compacted log. */
+    baseVersion(): number;
+    /**
+     * Highest known graph version — checkpoint anchor or the max recorded entry
+     * version, whichever is higher. Seeds the tool-layer counter so versions run on
+     * across sessions AND across compactions.
+     */
+    latestVersion(): number;
+    /**
+     * Archive the active log and start a fresh one anchored by a checkpoint line.
+     * Version-safe by construction: `latestVersion()` is identical before and after.
+     * No-op on a missing/empty log.
+     */
+    compact(reason?: string): {
+        archivedTo: string | null;
+        checkpointVersion: number;
+    };
+    private maybeCompact;
+    /** Read all parseable lines; skip a torn tail (crash mid-append) with a warning. */
+    private readLines;
+    private readEntries;
+}

package/dist/audit.js

@@ -0,0 +1,145 @@
+/**
+ * Operations log for tracking all graph mutations (CR-207).
+ *
+ * The operations log is a SUBSTRATE capability, not a graphcode-local one: it is
+ * the single source for OCC deltas, replay-merge, the learning feed, doc export,
+ * and rollback across the AiSE family (bok/.../02-operations-log-and-seams.md).
+ * It therefore lives here in graph-api-core with exactly one durable File
+ * implementation — the former graphcode `FileAuditLog` fork is lifted here (CR-207),
+ * no parallel implementation per consumer.
+ *
+ * `AuditLog` (record/query) is the minimal append/read surface — an in-memory
+ * variant is enough for tests. `OperationsLog` adds the durability surface the
+ * event-sourcing ladder needs: version continuity (`latestVersion`/`baseVersion`)
+ * and compaction (`compact`). `FileOperationsLog` persists an append-only JSONL
+ * stream, one file per store, checkpoint-anchored so the monotonic graph version
+ * survives every compaction, and torn-tail tolerant so a crash mid-append is a
+ * skipped line, never a read failure.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export class InMemoryAuditLog {
+    entries = [];
+    async record(entry) {
+        this.entries.push(entry);
+    }
+    async query(filter) {
+        let result = this.entries;
+        if (filter.consumerId) {
+            result = result.filter(e => e.consumerId === filter.consumerId);
+        }
+        if (filter.since) {
+            result = result.filter(e => e.timestamp >= filter.since);
+        }
+        if (filter.limit) {
+            result = result.slice(-filter.limit);
+        }
+        return result;
+    }
+}
+const isCheckpoint = (l) => l.checkpoint === true;
+/** Auto-compaction size threshold (bytes). */
+export const DEFAULT_COMPACT_BYTES = 10 * 1024 * 1024;
+/** Log filename inside the store dir — the log lives BESIDE the store it describes. */
+export const AUDIT_BASENAME = 'audit.jsonl';
+/** Standard-layout location relative to the repo root (store dir = `.graphcode`). */
+export const AUDIT_FILE = join('.graphcode', AUDIT_BASENAME);
+export class FileOperationsLog {
+    path;
+    maxBytes;
+    /**
+     * `storeDir` = the directory of the store this log describes (same anchoring rule
+     * as the ownership lock: per store, never per repo).
+     */
+    constructor(storeDir, opts) {
+        this.path = join(storeDir, AUDIT_BASENAME);
+        this.maxBytes = opts?.maxBytes ?? DEFAULT_COMPACT_BYTES;
+        // Session start is the safe compaction moment: no reader is mid-delta.
+        this.maybeCompact();
+    }
+    async record(entry) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        appendFileSync(this.path, JSON.stringify(entry) + '\n', 'utf8');
+    }
+    /** Mirrors InMemoryAuditLog semantics: `since` inclusive, `limit` = last N. */
+    async query(filter) {
+        let result = this.readEntries();
+        if (filter.consumerId)
+            result = result.filter(e => e.consumerId === filter.consumerId);
+        if (filter.since)
+            result = result.filter(e => e.timestamp >= filter.since);
+        if (filter.limit)
+            result = result.slice(-filter.limit);
+        return result;
+    }
+    /** The compaction anchor: checkpoint version, or 0 on a never-compacted log. */
+    baseVersion() {
+        const cp = this.readLines().find(isCheckpoint);
+        return cp?.version ?? 0;
+    }
+    /**
+     * Highest known graph version — checkpoint anchor or the max recorded entry
+     * version, whichever is higher. Seeds the tool-layer counter so versions run on
+     * across sessions AND across compactions.
+     */
+    latestVersion() {
+        let version = 0;
+        for (const l of this.readLines()) {
+            if (isCheckpoint(l))
+                version = Math.max(version, l.version);
+            else if (typeof l.graphVersion === 'number')
+                version = Math.max(version, l.graphVersion);
+        }
+        return version;
+    }
+    /**
+     * Archive the active log and start a fresh one anchored by a checkpoint line.
+     * Version-safe by construction: `latestVersion()` is identical before and after.
+     * No-op on a missing/empty log.
+     */
+    compact(reason = 'manual') {
+        if (!existsSync(this.path))
+            return { archivedTo: null, checkpointVersion: 0 };
+        const version = this.latestVersion();
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const archive = this.path.replace(/\.jsonl$/, `-${stamp}.jsonl`);
+        renameSync(this.path, archive);
+        const cp = { checkpoint: true, version, timestamp: new Date().toISOString(), reason };
+        writeFileSync(this.path, JSON.stringify(cp) + '\n', 'utf8');
+        return { archivedTo: archive, checkpointVersion: version };
+    }
+    maybeCompact() {
+        try {
+            if (existsSync(this.path) && statSync(this.path).size > this.maxBytes)
+                this.compact('auto-size');
+        }
+        catch {
+            // A stat/rename race only defers compaction to the next bind — never fatal.
+        }
+    }
+    /** Read all parseable lines; skip a torn tail (crash mid-append) with a warning. */
+    readLines() {
+        if (!existsSync(this.path))
+            return [];
+        const raw = readFileSync(this.path, 'utf8');
+        const lines = [];
+        let skipped = 0;
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                lines.push(JSON.parse(line));
+            }
+            catch {
+                skipped += 1;
+            }
+        }
+        if (skipped > 0) {
+            process.stderr.write(`[graph-api-core] WARN: ${this.path}: skipped ${skipped} unparseable line(s) (torn tail after a crash?).\n`);
+        }
+        return lines;
+    }
+    readEntries() {
+        return this.readLines().filter((l) => !isCheckpoint(l));
+    }
+}

package/dist/browser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @sigloch/graph-api-core/browser — browser-safe entry point.
+ *
+ * The main barrel (`./index.js`) re-exports `./audit.js`, whose durable
+ * `FileOperationsLog` statically imports `node:fs`/`node:path` (CR-207).
+ * A browser bundler externalizes those to a stub that THROWS on property
+ * access, so importing the barrel client-side dies at module-eval before a
+ * single React component mounts. Browser consumers (e.g. graph-view-edit's
+ * renderer/edit-surface) import ONLY the framework-agnostic, node-free
+ * surface from here instead — no operations-log, no store, no adapters.
+ *
+ * @author andreas@siglochconsulting
+ */
+export { findRoot } from './find-root.js';
+export type { RootQueryGraph } from './find-root.js';
+export { SE_DESCRIPTOR, projectToOntologyGraph } from './se-descriptor.js';
+export { FormatECodec } from './format-e-codec.js';
+export { isValidTrace, tracePatternsOf } from './types.js';
+export type { GraphNode, GraphEdge, Graph } from './types.js';
+export type { OntologyDescriptor, NodeTypeDescriptor, EdgeTypeDescriptor, TracePattern } from './types.js';
+export type { FormatEOperation, FormatEDiff } from './types.js';

package/dist/browser.js

@@ -0,0 +1,17 @@
+/**
+ * @sigloch/graph-api-core/browser — browser-safe entry point.
+ *
+ * The main barrel (`./index.js`) re-exports `./audit.js`, whose durable
+ * `FileOperationsLog` statically imports `node:fs`/`node:path` (CR-207).
+ * A browser bundler externalizes those to a stub that THROWS on property
+ * access, so importing the barrel client-side dies at module-eval before a
+ * single React component mounts. Browser consumers (e.g. graph-view-edit's
+ * renderer/edit-surface) import ONLY the framework-agnostic, node-free
+ * surface from here instead — no operations-log, no store, no adapters.
+ *
+ * @author andreas@siglochconsulting
+ */
+export { findRoot } from './find-root.js';
+export { SE_DESCRIPTOR, projectToOntologyGraph } from './se-descriptor.js';
+export { FormatECodec } from './format-e-codec.js';
+export { isValidTrace, tracePatternsOf } from './types.js';

package/dist/edge-ops.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure edge-rewiring semantics for update-edge / merge-nodes (CR-198).
+ * No storage access — GraphService.mutate() and the graphcode Apply-Gate
+ * both call this so flip/merge logic exists in exactly one place.
+ */
+import type { Graph, GraphEdge } from './types.js';
+export interface EdgeIdentity {
+    sourceId: string;
+    targetId: string;
+    edgeType: string;
+}
+export interface UpdateEdgeSet {
+    edgeType?: string;
+    flip?: boolean;
+    attributes?: Record<string, unknown>;
+}
+export interface UpdateEdgeResult {
+    graph: Graph;
+    removed: GraphEdge;
+    added: GraphEdge;
+}
+export interface MergeNodesResult {
+    graph: Graph;
+    removedNode: string;
+    removedEdges: GraphEdge[];
+    addedEdges: GraphEdge[];
+}
+export type EdgeOp = {
+    op: 'update-edge';
+    edge: EdgeIdentity;
+    set: UpdateEdgeSet;
+} | {
+    op: 'merge-nodes';
+    sourceUid: string;
+    targetUid: string;
+};
+/** Flip and/or retype an existing edge as one semantic op (old edge gone, new edge in). */
+export declare function updateEdge(graph: Graph, edge: EdgeIdentity, set: UpdateEdgeSet): UpdateEdgeResult;
+/** Absorb source into target: rewire all incident edges, drop source node, discard self-edges. */
+export declare function mergeNodes(graph: Graph, sourceUid: string, targetUid: string): MergeNodesResult;
+/** Dispatcher matching the contracts MutateCommand('update-edge'|'merge-nodes') shape. */
+export declare function applyEdgeOps(graph: Graph, op: EdgeOp): UpdateEdgeResult | MergeNodesResult;

package/dist/edge-ops.js

@@ -0,0 +1,66 @@
+function sameEdge(a, b) {
+    return a.sourceId === b.sourceId && a.targetId === b.targetId && a.edgeType === b.edgeType;
+}
+/** Flip and/or retype an existing edge as one semantic op (old edge gone, new edge in). */
+export function updateEdge(graph, edge, set) {
+    const idx = graph.edges.findIndex(e => sameEdge(e, edge));
+    if (idx === -1) {
+        throw new Error(`update-edge: edge not found: ${edge.sourceId} -${edge.edgeType}-> ${edge.targetId}`);
+    }
+    const existing = graph.edges[idx];
+    const added = {
+        sourceId: set.flip ? existing.targetId : existing.sourceId,
+        targetId: set.flip ? existing.sourceId : existing.targetId,
+        edgeType: set.edgeType ?? existing.edgeType,
+        attributes: set.attributes ? { ...existing.attributes, ...set.attributes } : existing.attributes,
+    };
+    const edges = graph.edges.slice();
+    edges.splice(idx, 1);
+    // A flip/retype can collide with an edge that already exists under the new
+    // identity (e.g. both directions of a relation are already present) — the
+    // result graph keeps one edge, not two identical ones.
+    if (!edges.some(e => sameEdge(e, added)))
+        edges.push(added);
+    return { graph: { ...graph, edges }, removed: existing, added };
+}
+/** Absorb source into target: rewire all incident edges, drop source node, discard self-edges. */
+export function mergeNodes(graph, sourceUid, targetUid) {
+    if (sourceUid === targetUid) {
+        throw new Error(`merge-nodes: source and target must differ (${sourceUid})`);
+    }
+    if (!graph.nodes.some(n => n.uid === sourceUid)) {
+        throw new Error(`merge-nodes: source node not found: ${sourceUid}`);
+    }
+    const edges = [];
+    const removedEdges = [];
+    const addedEdges = [];
+    for (const e of graph.edges) {
+        const touchesSource = e.sourceId === sourceUid || e.targetId === sourceUid;
+        if (!touchesSource) {
+            edges.push(e);
+            continue;
+        }
+        removedEdges.push(e);
+        const rewired = {
+            ...e,
+            sourceId: e.sourceId === sourceUid ? targetUid : e.sourceId,
+            targetId: e.targetId === sourceUid ? targetUid : e.targetId,
+        };
+        if (rewired.sourceId === rewired.targetId) {
+            continue; // self-edge created by rewiring — discarded
+        }
+        addedEdges.push(rewired);
+        // Two incident edges (or one incident + one pre-existing) can rewire onto
+        // the same (source,target,type) — keep the result graph free of duplicates.
+        if (!edges.some(x => sameEdge(x, rewired)))
+            edges.push(rewired);
+    }
+    const nodes = graph.nodes.filter(n => n.uid !== sourceUid);
+    return { graph: { nodes, edges }, removedNode: sourceUid, removedEdges, addedEdges };
+}
+/** Dispatcher matching the contracts MutateCommand('update-edge'|'merge-nodes') shape. */
+export function applyEdgeOps(graph, op) {
+    if (op.op === 'update-edge')
+        return updateEdge(graph, op.edge, op.set);
+    return mergeNodes(graph, op.sourceUid, op.targetUid);
+}

package/dist/factory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Factory for quick bootstrap of GraphService with adapters.
+ */
+import type { OntologyDescriptor } from './types.js';
+import { GraphService } from './graph-service.js';
+import type { StorageAdapter } from './storage-adapter.js';
+import type { TransportAdapter, TransportConfig } from './transport-adapter.js';
+export interface GraphApiConfig {
+    ontology: OntologyDescriptor;
+    storage?: StorageAdapter;
+    transport?: TransportAdapter;
+    transportConfig?: TransportConfig;
+}
+export interface GraphApi {
+    service: GraphService;
+    transport?: TransportAdapter;
+}
+/**
+ * Create and start a GraphService with optional transport.
+ *
+ * Minimal usage:
+ * ```ts
+ * const api = await createGraphApi({ ontology: myOntology })
+ * ```
+ */
+export declare function createGraphApi(config: GraphApiConfig): Promise<GraphApi>;

package/dist/factory.js

@@ -0,0 +1,23 @@
+import { GraphService } from './graph-service.js';
+import { MemoryAdapter } from './memory-adapter.js';
+/**
+ * Create and start a GraphService with optional transport.
+ *
+ * Minimal usage:
+ * ```ts
+ * const api = await createGraphApi({ ontology: myOntology })
+ * ```
+ */
+export async function createGraphApi(config) {
+    const storage = config.storage ?? new MemoryAdapter();
+    const service = new GraphService({
+        ontology: config.ontology,
+        storage,
+    });
+    await service.initialize();
+    if (config.transport) {
+        config.transport.mount(service, config.transportConfig ?? {});
+        await config.transport.start();
+    }
+    return { service, transport: config.transport };
+}

package/dist/find-root.d.ts

@@ -0,0 +1,34 @@
+/**
+ * findRoot — strukturelle Wurzel-Suche im SE-Ontologiegraph.
+ *
+ * Der Root ist der `SYS`-Knoten ("System (Wurzel)"), der KEINE eingehende
+ * `compose`-Kante hat — also nicht selbst als Sub-System unter einem anderen
+ * SYS hängt. Damit muss keine Wurzel-UID hardcodiert werden (vgl. das
+ * verdrahtete `SYS-gve` in graph-view-edit) und keine per Pfad-Hash abgeleitet
+ * werden (vgl. `projectSysId` in aimprove); die Wurzel wird aus der Struktur
+ * gefunden.
+ *
+ * Reihenfolge:
+ *   1. SYS-Knoten ohne eingehende compose-Kante  → der eigentliche Root.
+ *   2. sonst der erste SYS-Knoten                 → Fallback (Zyklus / defekter
+ *      Graph), damit ein Konsument nie ohne Anker dasteht.
+ *   3. sonst null                                 → kein SYS (leerer/neuer Graph).
+ *
+ * Strukturell typisiert (nur `elements`/`traces` mit den nötigen Feldern), damit
+ * sowohl `OntologyGraph` als auch der rohe Graph-JSON-Shape der Renderer passen.
+ *
+ * @author andreas@siglochconsulting
+ */
+export interface RootQueryGraph {
+    elements?: ReadonlyArray<{
+        id: string;
+        type: string;
+    }>;
+    traces?: ReadonlyArray<{
+        source: string;
+        target: string;
+        type: string;
+    }>;
+}
+/** Liefert die UID der Graph-Wurzel (SYS ohne eingehende compose) oder null. */
+export declare function findRoot(graph: RootQueryGraph | null | undefined): string | null;

package/dist/find-root.js

@@ -0,0 +1,10 @@
+/** Liefert die UID der Graph-Wurzel (SYS ohne eingehende compose) oder null. */
+export function findRoot(graph) {
+    const elements = graph?.elements ?? [];
+    const systems = elements.filter((e) => e.type === 'SYS');
+    if (systems.length === 0)
+        return null;
+    const composeTargets = new Set((graph?.traces ?? []).filter((t) => t.type === 'compose').map((t) => t.target));
+    const rootSys = systems.find((s) => !composeTargets.has(s.id));
+    return (rootSys ?? systems[0]).id;
+}

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

@@ -0,0 +1,23 @@
+import type { OntologyDescriptor, FormatEDiff, Graph } from './types.js';
+export declare class FormatECodec {
+    private readonly ontology;
+    private readonly edgeArrowToType;
+    private readonly validNodeTypes;
+    /** Trace-legality patterns (CR-GC-247) — the SSOT the parser validates edges against. */
+    private readonly patterns;
+    constructor(ontology: OntologyDescriptor);
+    /** Extract a ```format-e block from LLM output. Returns null if not found. */
+    extractFromLlm(llmOutput: string): string | null;
+    /** Parse Format E text into validated operations. */
+    parse(input: string): FormatEDiff;
+    /** Serialize a Graph to Format E text. */
+    serialize(graph: Graph): string;
+    private looksLikeNode;
+    private parseNodeLine;
+    private parseEdgeLine;
+    private parseMerge;
+    private extractNodeType;
+    private parseInlineAttrs;
+    private serializeAttrs;
+    private edgeTypeToArrow;
+}