backpack-ontology 0.2.25 → 0.3.0

package/dist/core/events.d.ts

@@ -0,0 +1,114 @@
+import type { Node, Edge, LearningGraphData, LearningGraphMetadata } from "./types.js";
+export declare const EVENT_SCHEMA_VERSION = 1;
+export type EventOp = "node.add" | "node.update" | "node.retype" | "node.remove" | "edge.add" | "edge.remove" | "edge.retype" | "metadata.update" | "snapshot.label";
+export interface BaseEvent {
+    /** Schema version for forward-compat checks. */
+    v: number;
+    /** ISO timestamp the event was created. */
+    ts: string;
+    /** Optional author identifier (e.g. machine ID, user email). */
+    author?: string;
+    /** Operation discriminator. */
+    op: EventOp;
+}
+export interface NodeAddEvent extends BaseEvent {
+    op: "node.add";
+    node: Node;
+}
+export interface NodeUpdateEvent extends BaseEvent {
+    op: "node.update";
+    id: string;
+    /** Properties to merge into the existing node. Pass `null` for a key to delete it. */
+    properties: Record<string, unknown>;
+}
+export interface NodeRetypeEvent extends BaseEvent {
+    op: "node.retype";
+    id: string;
+    /** New type for the node. The ID and properties are unchanged. */
+    type: string;
+}
+export interface NodeRemoveEvent extends BaseEvent {
+    op: "node.remove";
+    id: string;
+}
+export interface EdgeAddEvent extends BaseEvent {
+    op: "edge.add";
+    edge: Edge;
+}
+export interface EdgeRemoveEvent extends BaseEvent {
+    op: "edge.remove";
+    id: string;
+}
+export interface EdgeRetypeEvent extends BaseEvent {
+    op: "edge.retype";
+    id: string;
+    /** New type for the edge. The ID, endpoints, and properties are unchanged. */
+    type: string;
+}
+export interface MetadataUpdateEvent extends BaseEvent {
+    op: "metadata.update";
+    patch: Partial<Pick<LearningGraphMetadata, "name" | "description">>;
+}
+export interface SnapshotLabelEvent extends BaseEvent {
+    op: "snapshot.label";
+    /** Optional human-readable label. */
+    label?: string;
+}
+export type GraphEvent = NodeAddEvent | NodeUpdateEvent | NodeRetypeEvent | NodeRemoveEvent | EdgeAddEvent | EdgeRemoveEvent | EdgeRetypeEvent | MetadataUpdateEvent | SnapshotLabelEvent;
+export declare class EventReplayError extends Error {
+    readonly eventIndex: number;
+    readonly event: GraphEvent | null;
+    constructor(message: string, eventIndex: number, event: GraphEvent | null);
+}
+export declare function makeNodeAddEvent(node: Node, author?: string): NodeAddEvent;
+export declare function makeNodeUpdateEvent(id: string, properties: Record<string, unknown>, author?: string): NodeUpdateEvent;
+export declare function makeNodeRetypeEvent(id: string, type: string, author?: string): NodeRetypeEvent;
+export declare function makeNodeRemoveEvent(id: string, author?: string): NodeRemoveEvent;
+export declare function makeEdgeAddEvent(edge: Edge, author?: string): EdgeAddEvent;
+export declare function makeEdgeRemoveEvent(id: string, author?: string): EdgeRemoveEvent;
+export declare function makeEdgeRetypeEvent(id: string, type: string, author?: string): EdgeRetypeEvent;
+export declare function makeMetadataUpdateEvent(patch: Partial<Pick<LearningGraphMetadata, "name" | "description">>, author?: string): MetadataUpdateEvent;
+export declare function makeSnapshotLabelEvent(label?: string, author?: string): SnapshotLabelEvent;
+/**
+ * Apply a sequence of events on top of an existing state. Pure function:
+ * does not mutate inputs. Use this when you already have a materialized
+ * state and want to extend it with newly-appended events.
+ */
+export declare function applyEvents(state: LearningGraphData, events: GraphEvent[]): LearningGraphData;
+/**
+ * Replay a sequence of events into a LearningGraphData state, starting
+ * from an empty state with the given metadata. Pure function: no IO, no
+ * mutation of inputs.
+ *
+ * Throws EventReplayError on the first invalid event. The error
+ * carries the event index so the caller can locate the problem in
+ * the source log.
+ */
+export declare function replay(events: GraphEvent[], initialMetadata: LearningGraphMetadata): LearningGraphData;
+/**
+ * Compute the minimal sequence of events that would transform `before`
+ * into `after`. Used by the storage backend's `saveOntology` to support
+ * coarse-grained "save the whole graph" callers transparently.
+ *
+ * Detection rules:
+ *   - Nodes present in `after` but not `before`: node.add
+ *   - Nodes present in `before` but not `after`: node.remove (cascades to edges)
+ *   - Nodes present in both with different properties: node.update
+ *   - Edges present in `after` but not `before`: edge.add
+ *   - Edges present in `before` but not `after`: edge.remove
+ *   - Metadata name/description differences: metadata.update
+ */
+export declare function diffToEvents(before: LearningGraphData, after: LearningGraphData, author?: string): GraphEvent[];
+/**
+ * Serialize an event to a single JSONL line (no trailing newline).
+ */
+export declare function serializeEvent(event: GraphEvent): string;
+/**
+ * Parse a single JSONL line into an event. Throws on malformed input.
+ */
+export declare function parseEvent(line: string): GraphEvent;
+/**
+ * Parse a full JSONL document into an array of events. Skips blank lines.
+ */
+export declare function parseEventLog(text: string): GraphEvent[];
+//# sourceMappingURL=events.d.ts.map

package/dist/core/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"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"}

package/dist/core/events.js

@@ -0,0 +1,375 @@
+// ============================================================
+// Event types and replay logic for event-sourced learning graphs.
+//
+// A graph branch is an append-only sequence of events. The current
+// state of the branch is the result of replaying all events from the
+// beginning. Snapshots are events with a `label` field. Rollback is
+// truncating the event log at a snapshot's position.
+//
+// This module is pure: events in, state out, no IO. The storage
+// backend handles persistence; this module handles semantics.
+// ============================================================
+// --- Event schema version ---
+//
+// Bumped when the event format changes incompatibly. The replay function
+// rejects events with a version it doesn't know.
+export const EVENT_SCHEMA_VERSION = 1;
+// --- Errors ---
+export class EventReplayError extends Error {
+    eventIndex;
+    event;
+    constructor(message, eventIndex, event) {
+        super(`event ${eventIndex}: ${message}`);
+        this.eventIndex = eventIndex;
+        this.event = event;
+        this.name = "EventReplayError";
+    }
+}
+// --- Helpers ---
+function nowISO() {
+    return new Date().toISOString();
+}
+export function makeNodeAddEvent(node, author) {
+    return { v: EVENT_SCHEMA_VERSION, ts: nowISO(), author, op: "node.add", node };
+}
+export function makeNodeUpdateEvent(id, properties, author) {
+    return {
+        v: EVENT_SCHEMA_VERSION,
+        ts: nowISO(),
+        author,
+        op: "node.update",
+        id,
+        properties,
+    };
+}
+export function makeNodeRetypeEvent(id, type, author) {
+    return {
+        v: EVENT_SCHEMA_VERSION,
+        ts: nowISO(),
+        author,
+        op: "node.retype",
+        id,
+        type,
+    };
+}
+export function makeNodeRemoveEvent(id, author) {
+    return { v: EVENT_SCHEMA_VERSION, ts: nowISO(), author, op: "node.remove", id };
+}
+export function makeEdgeAddEvent(edge, author) {
+    return { v: EVENT_SCHEMA_VERSION, ts: nowISO(), author, op: "edge.add", edge };
+}
+export function makeEdgeRemoveEvent(id, author) {
+    return { v: EVENT_SCHEMA_VERSION, ts: nowISO(), author, op: "edge.remove", id };
+}
+export function makeEdgeRetypeEvent(id, type, author) {
+    return {
+        v: EVENT_SCHEMA_VERSION,
+        ts: nowISO(),
+        author,
+        op: "edge.retype",
+        id,
+        type,
+    };
+}
+export function makeMetadataUpdateEvent(patch, author) {
+    return {
+        v: EVENT_SCHEMA_VERSION,
+        ts: nowISO(),
+        author,
+        op: "metadata.update",
+        patch,
+    };
+}
+export function makeSnapshotLabelEvent(label, author) {
+    return { v: EVENT_SCHEMA_VERSION, ts: nowISO(), author, op: "snapshot.label", label };
+}
+// --- Replay / apply ---
+/**
+ * Apply a sequence of events on top of an existing state. Pure function:
+ * does not mutate inputs. Use this when you already have a materialized
+ * state and want to extend it with newly-appended events.
+ */
+export function applyEvents(state, events) {
+    return doReplay(events, state.metadata, state);
+}
+/**
+ * Replay a sequence of events into a LearningGraphData state, starting
+ * from an empty state with the given metadata. Pure function: no IO, no
+ * mutation of inputs.
+ *
+ * Throws EventReplayError on the first invalid event. The error
+ * carries the event index so the caller can locate the problem in
+ * the source log.
+ */
+export function replay(events, initialMetadata) {
+    return doReplay(events, initialMetadata, null);
+}
+function doReplay(events, initialMetadata, startingState) {
+    // Mutable accumulators (released as the immutable result on return)
+    const nodes = new Map();
+    const edges = new Map();
+    let metadata = { ...initialMetadata };
+    if (startingState) {
+        for (const node of startingState.nodes) {
+            nodes.set(node.id, { ...node });
+        }
+        for (const edge of startingState.edges) {
+            edges.set(edge.id, { ...edge });
+        }
+        metadata = { ...startingState.metadata };
+    }
+    for (let i = 0; i < events.length; i++) {
+        const event = events[i];
+        if (!event || typeof event !== "object") {
+            throw new EventReplayError("event is not an object", i, null);
+        }
+        if (event.v !== EVENT_SCHEMA_VERSION) {
+            throw new EventReplayError(`unknown event schema version ${event.v}`, i, event);
+        }
+        switch (event.op) {
+            case "node.add": {
+                if (nodes.has(event.node.id)) {
+                    throw new EventReplayError(`node ${event.node.id} already exists`, i, event);
+                }
+                nodes.set(event.node.id, { ...event.node });
+                break;
+            }
+            case "node.update": {
+                const existing = nodes.get(event.id);
+                if (!existing) {
+                    throw new EventReplayError(`node ${event.id} does not exist`, i, event);
+                }
+                const merged = { ...existing.properties };
+                for (const [key, value] of Object.entries(event.properties)) {
+                    if (value === null) {
+                        delete merged[key];
+                    }
+                    else {
+                        merged[key] = value;
+                    }
+                }
+                nodes.set(event.id, {
+                    ...existing,
+                    properties: merged,
+                    updatedAt: event.ts,
+                });
+                break;
+            }
+            case "node.retype": {
+                const existing = nodes.get(event.id);
+                if (!existing) {
+                    throw new EventReplayError(`node ${event.id} does not exist`, i, event);
+                }
+                nodes.set(event.id, {
+                    ...existing,
+                    type: event.type,
+                    updatedAt: event.ts,
+                });
+                break;
+            }
+            case "node.remove": {
+                if (!nodes.has(event.id)) {
+                    throw new EventReplayError(`node ${event.id} does not exist`, i, event);
+                }
+                nodes.delete(event.id);
+                // Cascade delete edges that reference this node
+                for (const [edgeId, edge] of edges) {
+                    if (edge.sourceId === event.id || edge.targetId === event.id) {
+                        edges.delete(edgeId);
+                    }
+                }
+                break;
+            }
+            case "edge.add": {
+                if (edges.has(event.edge.id)) {
+                    throw new EventReplayError(`edge ${event.edge.id} already exists`, i, event);
+                }
+                // Both endpoints must exist at the time of replay
+                if (!nodes.has(event.edge.sourceId)) {
+                    throw new EventReplayError(`edge ${event.edge.id} sourceId ${event.edge.sourceId} not in graph`, i, event);
+                }
+                if (!nodes.has(event.edge.targetId)) {
+                    throw new EventReplayError(`edge ${event.edge.id} targetId ${event.edge.targetId} not in graph`, i, event);
+                }
+                edges.set(event.edge.id, { ...event.edge });
+                break;
+            }
+            case "edge.remove": {
+                if (!edges.has(event.id)) {
+                    throw new EventReplayError(`edge ${event.id} does not exist`, i, event);
+                }
+                edges.delete(event.id);
+                break;
+            }
+            case "edge.retype": {
+                const existing = edges.get(event.id);
+                if (!existing) {
+                    throw new EventReplayError(`edge ${event.id} does not exist`, i, event);
+                }
+                edges.set(event.id, {
+                    ...existing,
+                    type: event.type,
+                    updatedAt: event.ts,
+                });
+                break;
+            }
+            case "metadata.update": {
+                metadata = {
+                    ...metadata,
+                    ...event.patch,
+                    updatedAt: event.ts,
+                };
+                break;
+            }
+            case "snapshot.label": {
+                // Snapshots are markers in the log. They don't change state.
+                break;
+            }
+            default: {
+                const exhaustive = event;
+                throw new EventReplayError(`unknown event op: ${exhaustive.op}`, i, exhaustive);
+            }
+        }
+    }
+    return {
+        metadata,
+        nodes: Array.from(nodes.values()),
+        edges: Array.from(edges.values()),
+    };
+}
+// --- Diff ---
+/**
+ * Compute the minimal sequence of events that would transform `before`
+ * into `after`. Used by the storage backend's `saveOntology` to support
+ * coarse-grained "save the whole graph" callers transparently.
+ *
+ * Detection rules:
+ *   - Nodes present in `after` but not `before`: node.add
+ *   - Nodes present in `before` but not `after`: node.remove (cascades to edges)
+ *   - Nodes present in both with different properties: node.update
+ *   - Edges present in `after` but not `before`: edge.add
+ *   - Edges present in `before` but not `after`: edge.remove
+ *   - Metadata name/description differences: metadata.update
+ */
+export function diffToEvents(before, after, author) {
+    const events = [];
+    // Metadata
+    const metaPatch = {};
+    if (before.metadata.name !== after.metadata.name) {
+        metaPatch.name = after.metadata.name;
+    }
+    if (before.metadata.description !== after.metadata.description) {
+        metaPatch.description = after.metadata.description;
+    }
+    if (Object.keys(metaPatch).length > 0) {
+        events.push(makeMetadataUpdateEvent(metaPatch, author));
+    }
+    const beforeNodes = new Map(before.nodes.map((n) => [n.id, n]));
+    const afterNodes = new Map(after.nodes.map((n) => [n.id, n]));
+    const beforeEdges = new Map(before.edges.map((e) => [e.id, e]));
+    const afterEdges = new Map(after.edges.map((e) => [e.id, e]));
+    // Removed edges first (so cascade-delete from removed nodes doesn't double-emit)
+    // Removed nodes will cascade their own edges in replay; we only need explicit
+    // edge removes for edges whose endpoints are NOT being removed.
+    const removedNodeIds = new Set();
+    for (const id of beforeNodes.keys()) {
+        if (!afterNodes.has(id))
+            removedNodeIds.add(id);
+    }
+    for (const [id, edge] of beforeEdges) {
+        if (afterEdges.has(id))
+            continue;
+        // Skip edges whose endpoints are being removed — the node.remove cascade handles them
+        if (removedNodeIds.has(edge.sourceId) || removedNodeIds.has(edge.targetId)) {
+            continue;
+        }
+        events.push(makeEdgeRemoveEvent(id, author));
+    }
+    // Removed nodes
+    for (const id of removedNodeIds) {
+        events.push(makeNodeRemoveEvent(id, author));
+    }
+    // Added + updated nodes
+    for (const [id, node] of afterNodes) {
+        const prev = beforeNodes.get(id);
+        if (!prev) {
+            events.push(makeNodeAddEvent(node, author));
+            continue;
+        }
+        // Type change: emit retype (preserves ID + edges)
+        if (prev.type !== node.type) {
+            events.push(makeNodeRetypeEvent(id, node.type, author));
+        }
+        // Property change: emit update with the property delta
+        if (JSON.stringify(prev.properties) !== JSON.stringify(node.properties)) {
+            const patch = {};
+            for (const [k, v] of Object.entries(node.properties)) {
+                if (!Object.prototype.hasOwnProperty.call(prev.properties, k)) {
+                    patch[k] = v;
+                }
+                else if (JSON.stringify(prev.properties[k]) !== JSON.stringify(v)) {
+                    patch[k] = v;
+                }
+            }
+            for (const k of Object.keys(prev.properties)) {
+                if (!Object.prototype.hasOwnProperty.call(node.properties, k)) {
+                    patch[k] = null;
+                }
+            }
+            events.push(makeNodeUpdateEvent(id, patch, author));
+        }
+    }
+    // Added edges + edge type changes
+    for (const [id, edge] of afterEdges) {
+        const prev = beforeEdges.get(id);
+        if (!prev) {
+            events.push(makeEdgeAddEvent(edge, author));
+            continue;
+        }
+        if (prev.type !== edge.type) {
+            events.push(makeEdgeRetypeEvent(id, edge.type, author));
+        }
+    }
+    return events;
+}
+// --- Serialization ---
+/**
+ * Serialize an event to a single JSONL line (no trailing newline).
+ */
+export function serializeEvent(event) {
+    return JSON.stringify(event);
+}
+/**
+ * Parse a single JSONL line into an event. Throws on malformed input.
+ */
+export function parseEvent(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+        throw new Error("empty event line");
+    }
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new Error("event must be an object");
+    }
+    return parsed;
+}
+/**
+ * Parse a full JSONL document into an array of events. Skips blank lines.
+ */
+export function parseEventLog(text) {
+    const events = [];
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim().length === 0)
+            continue;
+        try {
+            events.push(parseEvent(line));
+        }
+        catch (err) {
+            throw new Error(`parse error on line ${i + 1}: ${err.message}`);
+        }
+    }
+    return events;
+}
+//# sourceMappingURL=events.js.map

package/dist/core/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"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"}

package/dist/core/graph.d.ts

@@ -1,4 +1,4 @@
-import type { Node, Edge, LearningGraphData, NodeSummary, NodeTypeInfo, EdgeTypeInfo, ListNodesResult, GetNodeResult, NeighborResult, GraphStats, GraphAudit } from "./types.js";
+import type { Node, Edge, LearningGraphData, NodeSummary, NodeTypeInfo, EdgeTypeInfo, ListNodesResult, GetNodeResult, NeighborResult, GraphStats, GraphAudit, GraphDegreeTable } from "./types.js";
 /**
  * In-memory graph operations on an LearningGraphData object.
  * Pure logic — no I/O, no MCP, fully testable.
@@ -49,6 +49,8 @@ export declare class Graph {
     getEdgeTypes(): EdgeTypeInfo[];
     /** Compute graph statistics for diagnostics and improvement planning. */
     getStats(): GraphStats;
+    /** Full node degree table grouped by type, sorted by connectivity ascending. */
+    getDegreeTable(): GraphDegreeTable;
     /** Audit the graph and produce a structured improvement report. */
     audit(): GraphAudit;
     /** Bulk-import edges only (all nodes must already exist). Single atomic operation. */

package/dist/core/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/core/graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EACJ,IAAI,EACJ,iBAAiB,EACjB,WAAW,EAEX,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,aAAa,EAEb,cAAc,EACd,UAAU,EACV,UAAU,EAGX,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,qBAAa,KAAK;IACG,IAAI,EAAE,iBAAiB;gBAAvB,IAAI,EAAE,iBAAiB;IAI1C,OAAO,CAAC,GAAG;IAIX,+EAA+E;IAC/E,OAAO,CAAC,SAAS;IAOjB,wEAAwE;IACxE,OAAO,CAAC,aAAa;IAQrB,6CAA6C;IAC7C,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAchE;;;;OAIG;IACH,mBAAmB,CACjB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,EACnE,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;QACxB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACtC,CAAC,GACD;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;IA2C3C,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAWjE,uFAAuF;IACvF,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAiB9B,6DAA6D;IAC7D,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,eAAe;IAgBjE,sEAAsE;IACtE,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE;IA2BxD,qEAAqE;IACrE,YAAY,IAAI,YAAY,EAAE;IAU9B,qEAAqE;IACrE,YAAY,IAAI,YAAY,EAAE;IAU9B,yEAAyE;IACzE,QAAQ,IAAI,UAAU;IAkDtB,mEAAmE;IACnE,KAAK,IAAI,UAAU;IAyGnB,sFAAsF;IACtF,WAAW,CACT,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,GACvG,MAAM,EAAE;IAiBX,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACvC,IAAI;IAoBP,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAO5B,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa;IAW3C;;;OAGG;IACH,YAAY,CACV,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,GAAE,UAAU,GAAG,UAAU,GAAG,MAAe,EACpD,KAAK,SAAI,GACR,cAAc;CA8ClB"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/core/graph.ts"],"names":[],"mappings":"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"}

package/dist/core/graph.js

@@ -226,6 +226,56 @@ export class Graph {
                 .sort((a, b) => b.count - a.count),
         };
     }
+    /** Full node degree table grouped by type, sorted by connectivity ascending. */
+    getDegreeTable() {
+        const incoming = new Map();
+        const outgoing = new Map();
+        for (const edge of this.data.edges) {
+            outgoing.set(edge.sourceId, (outgoing.get(edge.sourceId) ?? 0) + 1);
+            incoming.set(edge.targetId, (incoming.get(edge.targetId) ?? 0) + 1);
+        }
+        const byType = new Map();
+        for (const node of this.data.nodes) {
+            const inc = incoming.get(node.id) ?? 0;
+            const out = outgoing.get(node.id) ?? 0;
+            const detail = {
+                id: node.id,
+                label: this.nodeLabel(node),
+                type: node.type,
+                incoming: inc,
+                outgoing: out,
+                total: inc + out,
+                propertyCount: Object.keys(node.properties).length,
+            };
+            const list = byType.get(node.type) ?? [];
+            list.push(detail);
+            byType.set(node.type, list);
+        }
+        const types = [];
+        for (const [type, nodes] of byType) {
+            nodes.sort((a, b) => a.total - b.total);
+            const totalConns = nodes.reduce((s, n) => s + n.total, 0);
+            const totalProps = nodes.reduce((s, n) => s + n.propertyCount, 0);
+            types.push({
+                type,
+                count: nodes.length,
+                avgConnections: Math.round((totalConns / nodes.length) * 10) / 10,
+                avgProperties: Math.round((totalProps / nodes.length) * 10) / 10,
+                nodes,
+            });
+        }
+        types.sort((a, b) => a.avgConnections - b.avgConnections);
+        const totalPossible = this.data.nodes.length * (this.data.nodes.length - 1) / 2;
+        const totalConns = [...incoming.values()].reduce((a, b) => a + b, 0)
+            + [...outgoing.values()].reduce((a, b) => a + b, 0);
+        return {
+            nodeCount: this.data.nodes.length,
+            edgeCount: this.data.edges.length,
+            density: totalPossible > 0 ? Math.round((this.data.edges.length / totalPossible) * 1000) / 1000 : 0,
+            avgConnections: this.data.nodes.length > 0 ? Math.round((totalConns / this.data.nodes.length) * 10) / 10 : 0,
+            types,
+        };
+    }
     /** Audit the graph and produce a structured improvement report. */
     audit() {
         const stats = this.getStats();