You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Serialisable graph representation with edge metadata #138
SpaceGraph is an in-process structure that can't be converted to JSON as it stands, and it drops edge metadata.
Not serialisable: it uses Map and Set, and its children maps hold full node objects instead of references. Consumers that receive a space over a process or network boundary, such as a browser UI fed by a server, can't receive a SpaceGraph. They have to ship SpaceNode[] plus the Hierarchy and rebuild the graph on the other side.
No edge metadata:children merges every edge (hierarchy and relationship) into one untyped map, and there's no parent or incoming-edge lookup. Each node's resolvedParents already carries the edge detail (field, source, hierarchy, fieldOn, selfRef), but the graph doesn't expose it. Consumers that need edges by relationship, or in either direction, have to build their own index from the raw nodes.
Not yet decided
The shape of a serialisable graph representation: titles as references, typed edges, in and out adjacency, and its relationship to the current SpaceGraph.
Which entry point would expose it. This depends on a broader look at how the public API divides into areas: runtime-agnostic code, plugin development, and filesystem- or config-dependent loading.
The design will be informed by a consumer-side index built outside sctx first, before any change to sctx is proposed.
changed the title [-]Browser-safe export for buildSpaceGraph (e.g. structured-context/graph)[/-][+]Serialisable graph representation with edge metadata[/+]on Oct 5, 2026
This comes from building a consumer-side index outside sctx first, as the issue suggested. A browser UI received SpaceNode[] plus the Hierarchy as JSON and indexed typed edges in both directions. That index worked, but every consumer would have had to write it again and keep it consistent. The proposal is for sctx to own both ends: a wire format, and a browser-safe function that rebuilds the graph from it, so every consumer ends up with the same SpaceGraph.
Wire format
The format follows graphology's serialisation format, without depending on graphology. It's the closest thing to a documented standard, and a consumer can run Graph.from(data) to get graphology's algorithms for free.
It's a multigraph. One pair of nodes can be linked through several fields, and self-referential edges exist.
Edges are the only source of truth.resolvedParents is left out on the wire and rebuilt by hydrate, so the two can't drift apart.
The serialiser drops dangling references. A filtered node set can contain parents that were filtered out; only edges with both ends present are emitted. hydrate throws on an unknown id.
The format covers every hierarchy. Every hierarchy and relationship edge is serialised. The hierarchy is picked when the graph is rebuilt, not when it is serialised, so one payload serves any view.
The format is versioned and has a schema.formatVersion is in the graph attributes, and a JSON Schema for the format is published with the bundled schemas.
API
serialiseSpaceGraph(nodes, hierarchies, meta) turns a graph into the wire format. Runs on Node.
hydrate(data, { hierarchy? }) turns the wire format into a SpaceGraph. It is browser-safe, and the hierarchy defaults to the schema's main hierarchy, as selectHierarchy does today.
SpaceGraph stays the in-memory view. It gains edge-aware lookups (childEdges(id) and parentEdges(id), which return typed edges), and the existing fields are unchanged.
The acceptance test is a round trip:hydrate(serialiseSpaceGraph(...)) must deep-equal buildSpaceGraph(...) on real spaces.
Entry point
hydrate is the first runtime code a browser consumer needs, and src/space-graph.ts already imports only types. So this needs a small browser-safe entry point, something like structured-context/graph, holding the format types, hydrate and buildSpaceGraph. It doesn't need the whole public API split up. Anything that imports node: modules stays in structured-context/api; dividing the rest of the API can wait until other runtime code needs to run in a browser.
Open points
The name of the entry point (/graph or /browser).
Whether sctx dump should emit this format, possibly behind a flag.
stcx dump - yes, with a flag. Assumption is existing SpaceNode[] dump is the more useful in general
Considerations:
serialiseSpaceGraph and hydrate should be named as a complementary pair IMO
Is the assumption that serialise produces a string or an object? The latter is more flexible, but also suggests a different verb than "serialise".
If graphology has Graph.from consider a similar construct. Assuming we don't have a Class/object, just function, eg exportSpaceGraph and spaceGraphFrom
Implemented in the linked PR. The decisions settled during implementation:
Names:exportSpaceGraph / spaceGraphFrom, which return and take objects, not strings.
Entry point:structured-context/browser exports spaceGraphFrom, SpaceGraph and SpaceNode. /api re-exports them and adds exportSpaceGraph. /browser imports nothing from /api.
Own format, not graphology's. Dangling edges (to nodes outside an exported subset) are kept, so the format breaks cleanly from graphology instead of being partly compatible.
Shape:{ formatVersion, hierarchies, mainHierarchy, nodes }. Edges stay in each node's resolvedParents, with no separate edge list.
Multiple hierarchies: the payload carries all of them, and the receiver picks one when it builds the graph. SpaceGraph stays a one-hierarchy view.
Edge rename:ResolvedParentRef.source is now kind (and _source is now _kind in filters), to avoid the clash with the source/target endpoint convention.
Edge lookups:parentEdges and childEdges are maps, matching the other SpaceGraph fields.
sctx dump --graph prints the format alone, without source or diagnostics.
JSON Schema: generated like the meta-schema. The source is a TS constant checked against the type at compile time, with a frozen copy per released formatVersion.
Activity
[-]Browser-safe export for buildSpaceGraph (e.g. structured-context/graph)[/-][+]Serialisable graph representation with edge metadata[/+]mindsocket commentedon Oct 26, 2026
Proposed design
This comes from building a consumer-side index outside sctx first, as the issue suggested. A browser UI received
SpaceNode[]plus theHierarchyas JSON and indexed typed edges in both directions. That index worked, but every consumer would have had to write it again and keep it consistent. The proposal is for sctx to own both ends: a wire format, and a browser-safe function that rebuilds the graph from it, so every consumer ends up with the sameSpaceGraph.Wire format
The format follows graphology's serialisation format, without depending on graphology. It's the closest thing to a documented standard, and a consumer can run
Graph.from(data)to get graphology's algorithms for free.{ "options": { "type": "directed", "multi": true, "allowSelfLoops": true }, "attributes": { "formatVersion": 1, "space": "…", "schemaId": "…", "hierarchies": [ /* Hierarchy */ ], "mainHierarchy": "…" }, "nodes": [{ "key": "<NodeId>", "attributes": { /* SpaceNode without resolvedParents */ } }], "edges": [{ "source": "<parent id>", "target": "<child id>", "attributes": { "field": "parent", "source": "hierarchy", "hierarchy": "…", "selfRef": false, "fieldOn": "child" } }] }resolvedParentsis left out on the wire and rebuilt byhydrate, so the two can't drift apart.hydratethrows on an unknown id.formatVersionis in the graph attributes, and a JSON Schema for the format is published with the bundled schemas.API
serialiseSpaceGraph(nodes, hierarchies, meta)turns a graph into the wire format. Runs on Node.hydrate(data, { hierarchy? })turns the wire format into aSpaceGraph. It is browser-safe, and the hierarchy defaults to the schema's mainhierarchy, asselectHierarchydoes today.SpaceGraphstays the in-memory view. It gains edge-aware lookups (childEdges(id)andparentEdges(id), which return typed edges), and the existing fields are unchanged.hydrate(serialiseSpaceGraph(...))must deep-equalbuildSpaceGraph(...)on real spaces.Entry point
hydrateis the first runtime code a browser consumer needs, andsrc/space-graph.tsalready imports only types. So this needs a small browser-safe entry point, something likestructured-context/graph, holding the format types,hydrateandbuildSpaceGraph. It doesn't need the whole public API split up. Anything that importsnode:modules stays instructured-context/api; dividing the rest of the API can wait until other runtime code needs to run in a browser.Open points
/graphor/browser).sctx dumpshould emit this format, possibly behind a flag.mindsocket commentedon Oct 27, 2026
Decisions:
Considerations:
Graph.fromconsider a similar construct. Assuming we don't have a Class/object, just function, egexportSpaceGraphandspaceGraphFrommindsocket commentedon Oct 27, 2026
Implemented in the linked PR. The decisions settled during implementation:
exportSpaceGraph/spaceGraphFrom, which return and take objects, not strings.structured-context/browserexportsspaceGraphFrom,SpaceGraphandSpaceNode./apire-exports them and addsexportSpaceGraph./browserimports nothing from/api.{ formatVersion, hierarchies, mainHierarchy, nodes }. Edges stay in each node'sresolvedParents, with no separate edge list.SpaceGraphstays a one-hierarchy view.ResolvedParentRef.sourceis nowkind(and_sourceis now_kindin filters), to avoid the clash with thesource/targetendpoint convention.parentEdgesandchildEdgesare maps, matching the otherSpaceGraphfields.sctx dump --graphprints the format alone, withoutsourceordiagnostics.formatVersion.refactor: rename edge `source` to `kind`
feat(graph): typed parentEdges and childEdges maps on SpaceGraph
feat(graph): space graph format with exportSpaceGraph and spaceGraphFrom
refactor(api): trim graph exports to what consumers need