Skip to content

Space graph format: exportSpaceGraph, spaceGraphFrom and structured-context/browser - #189

Merged
mindsocket merged 6 commits into
mainfrom
feat/138-space-graph-export
Oct 27, 2026
Merged

mindsocket merged 6 commits into
mainfrom
feat/138-space-graph-export

Conversation

@mindsocket

Copy link
Copy Markdown
Owner

Closes #138.

What changes

  • Space graph format. exportSpaceGraph(nodes, metadata) turns nodes and every hierarchy into plain JSON: { formatVersion, hierarchies, mainHierarchy, nodes }. spaceGraphFrom(data, { hierarchy }) builds a SpaceGraph from it, structured by the named hierarchy (default: the main hierarchy).
  • structured-context/browser. A browser-safe entry point exporting spaceGraphFrom, SpaceGraph and SpaceNode. /api re-exports all three and adds exportSpaceGraph. Other types are derived (for example Parameters<typeof spaceGraphFrom>[0]).
  • Typed edges on SpaceGraph. The new parentEdges and childEdges maps index each resolvedParents entry in both directions.
  • sctx dump --graph prints the format.
  • JSON Schema. The schema is a TS constant, and a typecheck fails if it and the type drift apart. It's generated to schemas/generated/space-graph/latest.json, with a frozen copy per released formatVersion. Generation fails if a released version's schema no longer matches.
  • Breaking (pre-1.0): the edge field source is renamed to kind on ResolvedParentRef, and _source to _kind in filter expressions.

Design decisions (differ from the issue's proposal)

  • Not graphology-compatible. Edges to nodes outside an exported subset are kept, which graphology can't load. So the format is our own, and it breaks cleanly from graphology.
  • No separate edge list. Edges stay in each node's resolvedParents, the one source of truth.
  • Hierarchy-agnostic data. The payload carries every hierarchy. The receiver picks one when it builds the graph, and SpaceGraph stays a one-hierarchy view.
  • Naming. exportSpaceGraph / spaceGraphFrom mirror graphology's export() / Graph.from() and return objects, not strings.

Testing

  • Round trip: spaceGraphFrom(exportSpaceGraph(...)) deep-equals buildSpaceGraph(...) for every hierarchy, on fixtures (including multi-hierarchy) and on a set of real local spaces.
  • Schema: exports from fixtures and the real spaces validate against the generated schema.
  • Browser bundle: /browser bundles for the browser without Node built-ins.
  • Package: the package test installs the tarball, runs dump --graph, and loads the output through structured-context/browser.

ResolvedParentRef.source becomes kind, and the filter metadata _source
becomes _kind. The edge `source` clashed with a node's source location
and with the source/target endpoint convention of graph formats.

Refs #138
Each resolvedParents entry becomes a SpaceEdge naming both ends, indexed
by child and by parent, so consumers can look up edges by relationship
in either direction without building their own index.

Refs #138
SpaceGraphData carries a space's nodes and every hierarchy as plain JSON,
so a graph can cross a process or network boundary. Edges stay in each
node's resolvedParents, including edges to nodes outside an exported
subset; the receiver picks the hierarchy when it builds the SpaceGraph.

- exportSpaceGraph(nodes, metadata) and spaceGraphFrom(data, { hierarchy })
- structured-context/browser: browser-safe entry point for the graph
  functions and node types; /api re-exports them
- sctx dump --graph prints SpaceGraphData
- JSON Schema generated to schemas/generated/space-graph/, frozen per
  released formatVersion; a typecheck fails if schema and type drift

Closes #138
/browser exports spaceGraphFrom with the SpaceGraph and SpaceNode types;
/api re-exports them from /browser and adds exportSpaceGraph. Other types
are derived from these.

Refs #138
@claude

claude Bot commented Oct 27, 2026

Copy link
Copy Markdown

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

@mindsocket
mindsocket merged commit 8ce9fd6 into main Oct 27, 2026
2 checks passed
@mindsocket
mindsocket deleted the feat/138-space-graph-export branch October 27, 2026 12:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Serialisable graph representation with edge metadata

1 participant