Reasoning extensions & contracts

The SvelteKit integration guide stops at the canvas seam: GraphData in, GraphCanvas out. When you need compare, lineage, projection, or evaluation over structured reasoning graphs, add the extensions package and @restormel/contracts — those concerns live outside Contract v0 (viewModel.ts), by design.

What it is

@restormel/graph-reasoning-extensions ships TypeScript helpers that operate on contracts-defined snapshots (for example GraphSnapshot, ReasoningObjectSnapshot). It is the same package SOPHIA and other hosts consume from npm — not a private fork.

• Depends on: @restormel/contracts (Zod-backed shapes) and @restormel/graph-core where types align — but it does not change Contract v0 DTOs.
• Semver: releases on git tag platform-v* with other platform packages. Version bumps can ship independently of graph-v* (canvas). Pin each package per your integration tests.

Export subpaths

Prefer subpath imports so bundlers tree-shake unused modules:

Import	Use when
@restormel/graph-reasoning-extensions/compare	Diff reasoning-object snapshots (diffReasoningSnapshots, related helpers).
@restormel/graph-reasoning-extensions/diff	Structural diff of two GraphSnapshot values (diffGraphs).
@restormel/graph-reasoning-extensions/evaluation	Graph evaluation passes (evaluateReasoningGraph, finding helpers).
@restormel/graph-reasoning-extensions/lineage	Lineage report + markdown rendering.
@restormel/graph-reasoning-extensions/projection	Project retrieval-like input to GraphSnapshot.
@restormel/graph-reasoning-extensions/summary	Compact summaries over a snapshot.
@restormel/graph-reasoning-extensions (barrel)	Re-exports all of the above; convenient, larger surface for static analysis.

When to use vs GraphData only

• GraphData + GraphCanvas only: interactive rendering, layout/trace/workspace, ghost layer, focus/dim — no shared reasoning-object pipeline.
• Add extensions + contracts: you compare snapshots, evaluate graphs, project retrieval into graph shapes, or emit lineage reports — then adapt results into GraphData for the canvas.

Minimal integration sketch (no SOPHIA required)

1. Add @restormel/contracts and @restormel/graph-reasoning-extensions to the app.
2. Run reasoning helpers on contracts types (diff, evaluate, …).
3. At the boundary, map nodes/edges (and optional highlight sets) into GraphData and pass props such as pathNodeIds / nodeSemanticStyles to GraphCanvas — see Recipes.

// Pseudocode: reasoning on @restormel/contracts shapes, render on GraphData.
import { diffGraphs } from "@restormel/graph-reasoning-extensions/diff";
import { evaluateReasoningGraph } from "@restormel/graph-reasoning-extensions/evaluation";
import type { GraphSnapshot } from "@restormel/contracts";
import type { GraphData } from "@restormel/graph-core/viewModel";

const before: GraphSnapshot = /* … */;
const after: GraphSnapshot = /* … */;
const delta = diffGraphs(before, after);

// Map delta.addedNodeIds / changedNodeIds into pathNodeIds or semantic styles,
// then pass GraphData into <GraphCanvas … /> (canvas stays contracts-free).

Source and publishing

Package root: packages/graph-reasoning-extensions. Programme context: phase1-restormel-engineering-spec.md, restormel-monorepo-packages.md. SOPHIA consumer notes: restormel-graph-sophia-consumer.md.

Related: context packs (Phase 2)

@restormel/context-packs (monorepo packages/context-packs) builds pass-specific LLM text from a portable retrieval-shaped payload. It is not part of the canvas packages; when published to npm, treat it as part of the graph-aware reasoning story (retrieval → packs → optional UI). Status: PHASE2-EXTRACTION-STATUS.md.

Related: Restormel State (agent memory)

@restormel/state adds an append-only memory event model, deterministic projectWorkingMemory, and correlation fields on context-pack inputs (and helpers for observability run_id alignment). Same platform-v* train as contracts, context-packs, and this extensions package—not graph-v*. Integrator overview: Restormel State (agent memory); repo spec: RESTORMEL-STATE.md.

← Docs home · Contract v0 scope · API reference