@restormel/graph-core 0.1.0

package/GRAPH_CORE_V0_SCOPE.md

@@ -0,0 +1,51 @@
+# `@restormel/graph-core` — Restormel Graph **Contract v0** scope
+
+This file **locks** what “v0” means for cross-platform work. In **restormel-keys**, `@restormel/graph-core` ships **only** Contract v0 plus the contracts-free helpers listed below. The SOPHIA app may still publish a broader `@restormel/graph-core` with legacy modules; consumers of this repo’s package should treat **this** tree as the MVP surface.
+
+## Contract v0 (frozen — platform review required to change)
+
+**Single source file:** `src/viewModel.ts`
+
+**Exported types (DTOs only):**
+
+- `GraphNode`, `GraphEdge`, `GraphGhostNode`, `GraphGhostEdge`
+- `GraphData`
+- `GraphViewportCommand`, `GraphRendererProps`
+- `GraphNodeSemanticStyle`, `GraphEdgeSemanticStyle`
+- Supporting unions: `GraphPhase`, `GraphNodeKind`, `GraphArcKind`, `GraphRejectionReasonCode`, `GraphConflictStatus`, `GraphViewportCommandType`
+
+**Invariants:**
+
+- No imports from SOPHIA or `@restormel/contracts`.
+- No runtime logic in `viewModel.ts` (types/interfaces only).
+
+## Explicitly **out of scope** for Contract v0 (future extraction targets)
+
+These modules **depend on `@restormel/contracts`** (or reasoning-object) and are **not** part of the frozen DTO contract:
+
+| Module | Role |
+|--------|------|
+| `compare.ts` | Reasoning snapshot compare |
+| `lineage.ts` | Lineage report / markdown |
+| `projection.ts` | Retrieval-like → graph snapshot |
+| `diff.ts` | Graph diff |
+| `evaluation.ts` | Reasoning graph evaluation |
+| `summary.ts` | Snapshot summary |
+
+Do **not** import these from a minimal Restormel Graph dashboard that only needs interactive rendering.
+
+## Co-located **render utilities** (zero `contracts` import today)
+
+SOPHIA’s `GraphCanvas` currently imports these from the same package; they are **not** the frozen DTO file but are **allowed dependencies** for SVG rendering until moved to `ui-graph-svelte`:
+
+| Module | Role |
+|--------|------|
+| `layout.ts` | `computeLayout` (orbital placement) |
+| `trace.ts` | `getNodeTraceTags`, `getNodeTraceLabel`, `formatTraceTag` (label formatting) |
+| `workspace.ts` | Generic filter/scope helpers (`WorkspaceGraphLike` — no contracts) |
+
+Restormel may vendor or co-publish these alongside Contract v0 when splitting packages.
+
+## Package dependency note
+
+**restormel-keys** `packages/graph-core` has **no** `@restormel/contracts` dependency. **Contract v0** (`viewModel.ts`) does not use that dependency.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Boon
+
+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/README.md

@@ -0,0 +1,32 @@
+# `@restormel/graph-core`
+
+**Restormel Graph Contract v0** — portable types and contracts-free helpers for interactive graph rendering.
+
+- **`viewModel.ts`** — frozen DTOs only (no runtime logic, no `@restormel/contracts`).
+- **`layout.ts`** — `computeLayout` (orbital placement).
+- **`trace.ts`** — trace tag / label helpers for canvas copy.
+- **`workspace.ts`** — generic filter and focus helpers (`WorkspaceGraphLike`, `filterGraph`, …).
+
+See **`GRAPH_CORE_V0_SCOPE.md`** for what is in v0 vs explicitly deferred (compare, lineage, projection, …).
+
+## Subpath exports
+
+After `pnpm run build`, Node resolves:
+
+- `@restormel/graph-core`
+- `@restormel/graph-core/viewModel`
+- `@restormel/graph-core/layout`
+- `@restormel/graph-core/trace`
+- `@restormel/graph-core/workspace`
+
+## Build
+
+```bash
+pnpm --filter @restormel/graph-core run build
+```
+
+## Tests
+
+```bash
+pnpm --filter @restormel/graph-core test
+```

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @restormel/graph-core — Restormel Graph MVP (Contract v0 + render helpers).
+ * Non-v0 modules (compare, lineage, …) are intentionally omitted; see GRAPH_CORE_V0_SCOPE.md.
+ */
+export * from './layout.js';
+export * from './trace.js';
+export * from './viewModel.js';
+export * from './workspace.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @restormel/graph-core — Restormel Graph MVP (Contract v0 + render helpers).
+ * Non-v0 modules (compare, lineage, …) are intentionally omitted; see GRAPH_CORE_V0_SCOPE.md.
+ */
+export * from './layout.js';
+export * from './trace.js';
+export * from './viewModel.js';
+export * from './workspace.js';

package/dist/layout.d.ts

@@ -0,0 +1,7 @@
+import type { GraphEdge, GraphNode } from './viewModel.js';
+export interface LayoutPosition {
+    x: number;
+    y: number;
+}
+export declare function computeLayout(nodes: GraphNode[], edges: GraphEdge[], width: number, height: number): Map<string, LayoutPosition>;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,EAAE,EAClB,KAAK,EAAE,SAAS,EAAE,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CA+C7B"}

package/dist/layout.js

@@ -0,0 +1,42 @@
+export function computeLayout(nodes, edges, width, height) {
+    const positions = new Map();
+    const centerX = width / 2;
+    const centerY = height / 2;
+    const outerRadius = Math.min(width, height) * 0.35;
+    const innerRadius = outerRadius * 0.6;
+    const sources = nodes.filter((node) => node.type === 'source');
+    const claims = nodes.filter((node) => node.type === 'claim');
+    sources.forEach((node, index) => {
+        const angle = (index / sources.length) * Math.PI * 2 - Math.PI / 2;
+        positions.set(node.id, {
+            x: centerX + Math.cos(angle) * outerRadius,
+            y: centerY + Math.sin(angle) * outerRadius
+        });
+    });
+    const claimsBySource = new Map();
+    for (const claim of claims) {
+        const sourceEdge = edges.find((edge) => edge.to === claim.id && edge.type === 'contains');
+        const sourceId = sourceEdge?.from || 'orphan';
+        if (!claimsBySource.has(sourceId))
+            claimsBySource.set(sourceId, []);
+        claimsBySource.get(sourceId)?.push(claim);
+    }
+    for (const [sourceId, sourceClaims] of claimsBySource) {
+        const sourcePos = positions.get(sourceId);
+        const baseAngle = sourcePos
+            ? Math.atan2(sourcePos.y - centerY, sourcePos.x - centerX)
+            : 0;
+        sourceClaims.forEach((claim, index) => {
+            const offset = (index - sourceClaims.length / 2) * 0.3;
+            const angle = baseAngle + offset;
+            const radius = innerRadius +
+                (claim.id.split('').reduce((sum, char) => sum + char.charCodeAt(0), 0) % 20) -
+                10;
+            positions.set(claim.id, {
+                x: centerX + Math.cos(angle) * radius,
+                y: centerY + Math.sin(angle) * radius
+            });
+        });
+    }
+    return positions;
+}

package/dist/trace.d.ts

@@ -0,0 +1,5 @@
+import type { GraphNode } from './viewModel.js';
+export declare function getNodeTraceTags(node: GraphNode): string[];
+export declare function getNodeTraceLabel(node: GraphNode, maxTags?: number): string;
+export declare function formatTraceTag(tag: string): string;
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,CAS1D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,SAAI,GAAG,MAAM,CAEtE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/trace.js

@@ -0,0 +1,22 @@
+export function getNodeTraceTags(node) {
+    const tags = [];
+    if (node.isSeed)
+        tags.push('seed');
+    else if (node.isTraversed)
+        tags.push('traversed');
+    if (node.pass_origin)
+        tags.push(node.pass_origin);
+    if (node.conflict_status && node.conflict_status !== 'none')
+        tags.push(node.conflict_status);
+    if (node.unresolved_tension_id)
+        tags.push('tension');
+    if (node.provenance_id)
+        tags.push('provenanced');
+    return tags;
+}
+export function getNodeTraceLabel(node, maxTags = 4) {
+    return getNodeTraceTags(node).slice(0, maxTags).join(' · ');
+}
+export function formatTraceTag(tag) {
+    return tag.replaceAll('_', ' ');
+}

package/dist/viewModel.d.ts

@@ -0,0 +1,148 @@
+/**
+ * RESTORMEL GRAPH CONTRACT v0
+ * DO NOT MODIFY WITHOUT PLATFORM REVIEW
+ *
+ * Frozen DTOs for interactive graph rendering. This file is the only graph-core surface
+ * that defines cross-platform data shape for Restormel Graph MVP.
+ *
+ * Rules:
+ * - No imports from SOPHIA, `@restormel/contracts`, or any app package.
+ * - No runtime logic — types and interfaces only.
+ *
+ * Portable graph view-model for rendering (Restormel Graph).
+ * Hosts map domain snapshots into these shapes; renderers consume `GraphData` + optional semantics.
+ */
+export type GraphPhase = 'retrieval' | 'analysis' | 'critique' | 'synthesis';
+export type GraphNodeKind = 'source' | 'claim';
+export type GraphConflictStatus = 'none' | 'contested' | 'unresolved' | 'resolved';
+export type GraphArcKind = 'contains' | 'supports' | 'contradicts' | 'responds-to' | 'depends-on' | 'defines' | 'qualifies' | 'assumes' | 'resolves';
+export type GraphRejectionReasonCode = 'seed_pool_pruned' | 'duplicate_traversal' | 'duplicate_relation' | 'missing_endpoint' | 'confidence_gate' | 'source_integrity_gate';
+/** Vertex shown in the interactive graph canvas. */
+export interface GraphNode {
+    id: string;
+    type: GraphNodeKind;
+    label: string;
+    phase?: GraphPhase;
+    domain?: string;
+    sourceTitle?: string;
+    traversalDepth?: number;
+    relevance?: number;
+    isSeed?: boolean;
+    isTraversed?: boolean;
+    confidenceBand?: 'high' | 'medium' | 'low';
+    depth_level?: number;
+    evidence_strength?: number;
+    novelty_score?: number;
+    derived_from?: string[];
+    pass_origin?: GraphPhase;
+    conflict_status?: GraphConflictStatus;
+    unresolved_tension_id?: string;
+    provenance_id?: string;
+}
+/** Directed typed edge between vertices. */
+export interface GraphEdge {
+    from: string;
+    to: string;
+    type: GraphArcKind;
+    weight?: number;
+    phaseOrigin?: GraphPhase;
+    depth_level?: number;
+    evidence_strength?: number;
+    novelty_score?: number;
+    derived_from?: string[];
+    pass_origin?: GraphPhase;
+    conflict_status?: GraphConflictStatus;
+    unresolved_tension_id?: string;
+    provenance_id?: string;
+    relation_rationale?: string;
+    relation_confidence?: number;
+    evidence_count?: number;
+    evidence_sources?: string[];
+}
+/** Rejected / ghost vertex (optional overlay). */
+export interface GraphGhostNode {
+    id: string;
+    label: string;
+    reasonCode: GraphRejectionReasonCode;
+    consideredIn?: 'seed_pool' | 'traversal' | 'relations';
+    sourceTitle?: string;
+    confidence?: number;
+    anchorNodeId?: string;
+    pass_origin?: GraphPhase;
+}
+/** Rejected / ghost edge (optional overlay). */
+export interface GraphGhostEdge {
+    id: string;
+    from: string;
+    to: string;
+    type: GraphArcKind;
+    reasonCode: GraphRejectionReasonCode;
+    relation_confidence?: number;
+    rationale_source?: string;
+    pass_origin?: GraphPhase;
+}
+/** Bundle passed to a graph renderer (nodes + primary edges + optional ghost layer). */
+export interface GraphData {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    ghostNodes: GraphGhostNode[];
+    ghostEdges: GraphGhostEdge[];
+}
+export type GraphViewportCommandType = 'fit' | 'reset-layout';
+export interface GraphViewportCommand {
+    type: GraphViewportCommandType;
+    nonce: number;
+}
+/**
+ * Semantic styling keyed by node id and by edge key `from:type:to`
+ * (see `graphCanvasEdgeKey` in host or duplicate in ui package).
+ */
+export type GraphNodeSemanticStyle = {
+    kind: string;
+    shape: 'circle' | 'square' | 'diamond' | 'hexagon' | 'rounded-rect';
+    fill: string;
+    stroke: string;
+    glyph?: string;
+    radius?: number;
+    state?: 'default' | 'verified' | 'unresolved' | 'contradicted' | 'synthesis';
+};
+export type GraphEdgeSemanticStyle = {
+    kind: string;
+    stroke: string;
+    strokeWidth?: number;
+    dasharray?: string;
+    marker?: 'arrow-blue' | 'arrow-teal' | 'arrow-coral' | 'arrow-amber' | 'arrow-purple' | 'none';
+    state?: 'default' | 'verified' | 'unresolved' | 'contradicted' | 'synthesis';
+};
+/** Props contract for the Svelte graph canvas (`@restormel/ui-graph-svelte`). */
+export interface GraphRendererProps {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    ghostNodes?: GraphGhostNode[];
+    ghostEdges?: GraphGhostEdge[];
+    showGhostLayer?: boolean;
+    showInlineDetail?: boolean;
+    showStatusChip?: boolean;
+    showViewportControls?: boolean;
+    viewportCommand?: GraphViewportCommand | null;
+    nodeSemanticStyles?: Record<string, GraphNodeSemanticStyle>;
+    edgeSemanticStyles?: Record<string, GraphEdgeSemanticStyle>;
+    width?: number;
+    height?: number;
+    isFullscreen?: boolean;
+    onToggleFullscreen?: () => void;
+    pinnedNodeIds?: string[];
+    pathNodeIds?: string[];
+    pathEdges?: Array<{
+        from: string;
+        to: string;
+    }>;
+    focusNodeIds?: string[];
+    focusEdgeIds?: string[];
+    dimOutOfScope?: boolean;
+    selectedNodeId?: string | null;
+    onSelectedNodeChange?: (nodeId: string | null) => void;
+    onNodeSelect?: (nodeId: string) => void;
+    onJumpToReferences?: (nodeId: string) => void;
+}
+//# sourceMappingURL=viewModel.d.ts.map

package/dist/viewModel.d.ts.map

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

package/dist/viewModel.js

@@ -0,0 +1,15 @@
+/**
+ * RESTORMEL GRAPH CONTRACT v0
+ * DO NOT MODIFY WITHOUT PLATFORM REVIEW
+ *
+ * Frozen DTOs for interactive graph rendering. This file is the only graph-core surface
+ * that defines cross-platform data shape for Restormel Graph MVP.
+ *
+ * Rules:
+ * - No imports from SOPHIA, `@restormel/contracts`, or any app package.
+ * - No runtime logic — types and interfaces only.
+ *
+ * Portable graph view-model for rendering (Restormel Graph).
+ * Hosts map domain snapshots into these shapes; renderers consume `GraphData` + optional semantics.
+ */
+export {};

package/dist/workspace.d.ts

@@ -0,0 +1,88 @@
+export interface WorkspaceGraphLikeNode<NodeKind extends string = string, Phase extends string = string> {
+    id: string;
+    kind: NodeKind;
+    phase?: Phase;
+    searchText: string;
+}
+export interface WorkspaceGraphLikeEdge<EdgeKind extends string = string, Phase extends string = string> {
+    id: string;
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    phase?: Phase;
+}
+export interface WorkspaceGhostLikeNode {
+    anchorNodeId?: string;
+}
+export interface WorkspaceGhostLikeEdge {
+    from: string;
+    to: string;
+}
+export interface WorkspaceGraphLike<Node extends WorkspaceGraphLikeNode = WorkspaceGraphLikeNode, Edge extends WorkspaceGraphLikeEdge = WorkspaceGraphLikeEdge, GhostNode extends WorkspaceGhostLikeNode = WorkspaceGhostLikeNode, GhostEdge extends WorkspaceGhostLikeEdge = WorkspaceGhostLikeEdge> {
+    nodes: Node[];
+    edges: Edge[];
+    ghostNodes: GhostNode[];
+    ghostEdges: GhostEdge[];
+}
+export interface WorkspaceGraphFilters<NodeKind extends string, EdgeKind extends string, Phase extends string> {
+    search: string;
+    phase: 'all' | Phase;
+    density: 'comfortable' | 'dense';
+    nodeKinds: Set<NodeKind>;
+    edgeKinds: Set<EdgeKind>;
+    showGhosts: boolean;
+}
+export interface WorkspaceFocusScope {
+    nodeIds: string[];
+    edgeIds: string[];
+}
+export interface WorkspacePathFocus {
+    nodeIds: string[];
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+export interface WorkspaceScopeSummary {
+    active: boolean;
+    visibleNodes: number;
+    totalNodes: number;
+    visibleEdges: number;
+    totalEdges: number;
+}
+export declare function reconcileKindSelection<T extends string>(current: Set<T>, available: Set<T>): Set<T>;
+export declare function toggleKindSelection<T extends string>(current: Set<T>, value: T, fallback: Set<T>): Set<T>;
+export declare function collectNodeKinds<Node extends {
+    kind: string;
+}>(nodes: Node[]): Set<Node['kind']>;
+export declare function collectEdgeKinds<Edge extends {
+    kind: string;
+}>(edges: Edge[]): Set<Edge['kind']>;
+export declare function filterGraph<Node extends WorkspaceGraphLikeNode, Edge extends WorkspaceGraphLikeEdge, GhostNode extends WorkspaceGhostLikeNode, GhostEdge extends WorkspaceGhostLikeEdge, Graph extends WorkspaceGraphLike<Node, Edge, GhostNode, GhostEdge>>(graph: Graph, filters: WorkspaceGraphFilters<Node['kind'], Edge['kind'], NonNullable<Node['phase']>>, selectedNodeId: string | null, options?: {
+    comfortableHiddenEdgeKinds?: Edge['kind'][];
+}): Graph;
+export declare function collectNeighborhoodScope<Edge extends WorkspaceGraphLikeEdge>(graph: Pick<WorkspaceGraphLike<WorkspaceGraphLikeNode, Edge>, 'edges'>, centerNodeId: string | null, maxHops: number): WorkspaceFocusScope;
+export declare function isolateGraphToScope<Node extends WorkspaceGraphLikeNode, Edge extends WorkspaceGraphLikeEdge, GhostNode extends WorkspaceGhostLikeNode, GhostEdge extends WorkspaceGhostLikeEdge, Graph extends WorkspaceGraphLike<Node, Edge, GhostNode, GhostEdge>>(graph: Graph, scope: WorkspaceFocusScope): Graph;
+export declare function buildSelectionPathFocus<Node extends WorkspaceGraphLikeNode, Edge extends WorkspaceGraphLikeEdge>(graph: Pick<WorkspaceGraphLike<Node, Edge>, 'edges'>, selectedNodeId: string | null, enabled: boolean, options: {
+    highlightEdgeKinds: Edge['kind'][];
+}): WorkspacePathFocus;
+export declare function mergePathFocuses(...paths: WorkspacePathFocus[]): WorkspacePathFocus;
+export declare function buildFocusSummary(params: {
+    focusMode: string;
+    scopeNodeIds: string[];
+    scopeEdgeIds: string[];
+    totalNodes: number;
+    totalEdges: number;
+}): WorkspaceScopeSummary;
+export declare function buildReadabilityWarnings<Node extends {
+    kind: string;
+}, Edge extends {
+    kind: string;
+}>(graph: Pick<WorkspaceGraphLike<Node & WorkspaceGraphLikeNode, Edge & WorkspaceGraphLikeEdge>, 'nodes' | 'edges'>, options?: {
+    sourceNodeKinds?: Node['kind'][];
+    lowSourceThreshold?: number;
+    crowdedNodeThreshold?: number;
+    denseEdgeFloor?: number;
+    structuralEdgeKinds?: Edge['kind'][];
+}): string[];
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

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

package/dist/workspace.js

@@ -0,0 +1,202 @@
+function setsEqual(left, right) {
+    if (left.size !== right.size)
+        return false;
+    for (const value of left) {
+        if (!right.has(value))
+            return false;
+    }
+    return true;
+}
+export function reconcileKindSelection(current, available) {
+    if (available.size === 0) {
+        return current.size === 0 ? current : new Set();
+    }
+    if (current.size === 0) {
+        return setsEqual(current, available) ? current : new Set(available);
+    }
+    const next = new Set();
+    for (const value of current) {
+        if (available.has(value))
+            next.add(value);
+    }
+    if (next.size > 0) {
+        return setsEqual(current, next) ? current : next;
+    }
+    return setsEqual(current, available) ? current : new Set(available);
+}
+export function toggleKindSelection(current, value, fallback) {
+    const next = new Set(current);
+    if (next.has(value))
+        next.delete(value);
+    else
+        next.add(value);
+    return next.size > 0 ? next : new Set(fallback);
+}
+export function collectNodeKinds(nodes) {
+    return new Set(nodes.map((node) => node.kind));
+}
+export function collectEdgeKinds(edges) {
+    return new Set(edges.map((edge) => edge.kind));
+}
+export function filterGraph(graph, filters, selectedNodeId, options) {
+    const search = filters.search.trim().toLowerCase();
+    const nodeMatches = (node) => {
+        if (filters.phase !== 'all' && node.phase && node.phase !== filters.phase)
+            return false;
+        if (!filters.nodeKinds.has(node.kind) && node.id !== selectedNodeId)
+            return false;
+        if (!search)
+            return true;
+        return node.searchText.toLowerCase().includes(search);
+    };
+    const matchedNodeIds = new Set(graph.nodes.filter(nodeMatches).map((node) => node.id));
+    if (selectedNodeId)
+        matchedNodeIds.add(selectedNodeId);
+    let edges = graph.edges.filter((edge) => {
+        if (!filters.edgeKinds.has(edge.kind))
+            return false;
+        if (filters.phase !== 'all' && edge.phase && edge.phase !== filters.phase)
+            return false;
+        return matchedNodeIds.has(edge.from) && matchedNodeIds.has(edge.to);
+    });
+    if (filters.density === 'comfortable') {
+        const hiddenKinds = new Set(options?.comfortableHiddenEdgeKinds ?? []);
+        const logicalEdges = edges.filter((edge) => !hiddenKinds.has(edge.kind));
+        if (logicalEdges.length > 0)
+            edges = logicalEdges;
+    }
+    const visibleNodeIds = new Set();
+    for (const edge of edges) {
+        visibleNodeIds.add(edge.from);
+        visibleNodeIds.add(edge.to);
+    }
+    if (selectedNodeId)
+        visibleNodeIds.add(selectedNodeId);
+    const nodes = graph.nodes.filter((node) => {
+        if (visibleNodeIds.size === 0)
+            return nodeMatches(node);
+        return visibleNodeIds.has(node.id) && nodeMatches(node);
+    });
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    return {
+        ...graph,
+        nodes,
+        edges,
+        ghostNodes: filters.showGhosts
+            ? graph.ghostNodes.filter((node) => !node.anchorNodeId || nodeIds.has(node.anchorNodeId))
+            : [],
+        ghostEdges: filters.showGhosts
+            ? graph.ghostEdges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to))
+            : []
+    };
+}
+export function collectNeighborhoodScope(graph, centerNodeId, maxHops) {
+    if (!centerNodeId || maxHops < 0) {
+        return { nodeIds: [], edgeIds: [] };
+    }
+    const visited = new Set([centerNodeId]);
+    const frontier = new Set([centerNodeId]);
+    const edgeIds = new Set();
+    for (let hop = 0; hop < maxHops; hop += 1) {
+        const nextFrontier = new Set();
+        for (const edge of graph.edges) {
+            const fromInFrontier = frontier.has(edge.from);
+            const toInFrontier = frontier.has(edge.to);
+            if (!fromInFrontier && !toInFrontier)
+                continue;
+            edgeIds.add(edge.id);
+            if (fromInFrontier && !visited.has(edge.to)) {
+                visited.add(edge.to);
+                nextFrontier.add(edge.to);
+            }
+            if (toInFrontier && !visited.has(edge.from)) {
+                visited.add(edge.from);
+                nextFrontier.add(edge.from);
+            }
+        }
+        if (nextFrontier.size === 0)
+            break;
+        frontier.clear();
+        for (const nodeId of nextFrontier)
+            frontier.add(nodeId);
+    }
+    return {
+        nodeIds: [...visited],
+        edgeIds: [...edgeIds]
+    };
+}
+export function isolateGraphToScope(graph, scope) {
+    if (scope.nodeIds.length === 0)
+        return graph;
+    const nodeIdSet = new Set(scope.nodeIds);
+    const edgeIdSet = new Set(scope.edgeIds);
+    return {
+        ...graph,
+        nodes: graph.nodes.filter((node) => nodeIdSet.has(node.id)),
+        edges: graph.edges.filter((edge) => edgeIdSet.has(edge.id)),
+        ghostNodes: graph.ghostNodes.filter((node) => !node.anchorNodeId || nodeIdSet.has(node.anchorNodeId)),
+        ghostEdges: graph.ghostEdges.filter((edge) => nodeIdSet.has(edge.from) && nodeIdSet.has(edge.to))
+    };
+}
+export function buildSelectionPathFocus(graph, selectedNodeId, enabled, options) {
+    if (!enabled || !selectedNodeId) {
+        return { nodeIds: [], edges: [] };
+    }
+    const highlightKinds = new Set(options.highlightEdgeKinds);
+    const edges = graph.edges
+        .filter((edge) => (edge.from === selectedNodeId || edge.to === selectedNodeId) &&
+        highlightKinds.has(edge.kind))
+        .map((edge) => ({ from: edge.from, to: edge.to }));
+    const nodeIds = new Set([selectedNodeId]);
+    for (const edge of edges) {
+        nodeIds.add(edge.from);
+        nodeIds.add(edge.to);
+    }
+    return { nodeIds: [...nodeIds], edges };
+}
+export function mergePathFocuses(...paths) {
+    const nodeIds = new Set();
+    const edgeMap = new Map();
+    for (const path of paths) {
+        for (const nodeId of path.nodeIds)
+            nodeIds.add(nodeId);
+        for (const edge of path.edges) {
+            edgeMap.set(`${edge.from}:${edge.to}`, edge);
+        }
+    }
+    return {
+        nodeIds: [...nodeIds],
+        edges: [...edgeMap.values()]
+    };
+}
+export function buildFocusSummary(params) {
+    return {
+        active: params.focusMode !== 'global' && params.scopeNodeIds.length > 0,
+        visibleNodes: params.scopeNodeIds.length,
+        totalNodes: params.totalNodes,
+        visibleEdges: params.scopeEdgeIds.length,
+        totalEdges: params.totalEdges
+    };
+}
+export function buildReadabilityWarnings(graph, options) {
+    const warnings = [];
+    const nodeCount = graph.nodes.length;
+    const edgeCount = graph.edges.length;
+    const sourceNodeKinds = new Set(options?.sourceNodeKinds ?? ['source']);
+    const structuralEdgeKinds = new Set(options?.structuralEdgeKinds ?? ['contains', 'retrieved-from']);
+    const sourceCount = graph.nodes.filter((node) => sourceNodeKinds.has(node.kind)).length;
+    const crossSourceEdgeCount = graph.edges.filter((edge) => !structuralEdgeKinds.has(edge.kind)).length;
+    if (nodeCount >= (options?.crowdedNodeThreshold ?? 36)) {
+        warnings.push('Orbital v1 starts to lose global readability once roughly 36+ visible nodes compete for label space.');
+    }
+    if (edgeCount >= Math.max(nodeCount * 2, options?.denseEdgeFloor ?? 24)) {
+        warnings.push('Dense relation overlays create heavy edge crossings; local focus or isolation is recommended.');
+    }
+    if (sourceCount <= (options?.lowSourceThreshold ?? 1) && nodeCount >= 18) {
+        warnings.push('When many claims share little source structure, the current source-centric layout collapses toward the center.');
+    }
+    if (crossSourceEdgeCount >= 18) {
+        warnings.push('Cross-source reasoning links are only weakly clustered today, so support and contradiction paths become harder to trace.');
+    }
+    return warnings;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@restormel/graph-core",
+  "version": "0.1.0",
+  "description": "Restormel Graph Contract v0 DTOs plus contracts-free layout, trace, and workspace helpers.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Allotment-Technology-Ltd/restormel-keys.git",
+    "directory": "packages/graph-core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./layout": {
+      "types": "./dist/layout.d.ts",
+      "import": "./dist/layout.js"
+    },
+    "./trace": {
+      "types": "./dist/trace.d.ts",
+      "import": "./dist/trace.js"
+    },
+    "./viewModel": {
+      "types": "./dist/viewModel.d.ts",
+      "import": "./dist/viewModel.js"
+    },
+    "./workspace": {
+      "types": "./dist/workspace.d.ts",
+      "import": "./dist/workspace.js"
+    }
+  },
+  "files": [
+    "dist",
+    "GRAPH_CORE_V0_SCOPE.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run"
+  }
+}