structured-context 0.15.0 → 0.17.0

package/dist/space-graph.js

@@ -3,10 +3,12 @@ export function buildSpaceGraph(nodes, hierarchy) {
     const levels = hierarchy?.levels ?? [];
     const hierarchyTypes = new Set(levels.map((l) => l.type));
     const rootType = levels[0]?.type;
-    const isHierarchyEdge = (r) => r.source === 'hierarchy' && r.hierarchy === hierarchy?.name;
+    const isHierarchyEdge = (r) => r.kind === 'hierarchy' && r.hierarchy === hierarchy?.name;
     const nodesMap = new Map();
     const hierarchyChildrenMap = new Map();
     const childrenMap = new Map();
+    const parentEdgesMap = new Map();
+    const childEdgesMap = new Map();
     const hierarchyRoots = [];
     const orphans = [];
     const nonHierarchy = [];
@@ -15,10 +17,18 @@ export function buildSpaceGraph(nodes, hierarchy) {
         nodesMap.set(node.id, node);
         hierarchyChildrenMap.set(node.id, []);
         childrenMap.set(node.id, []);
+        parentEdgesMap.set(node.id, []);
+        childEdgesMap.set(node.id, []);
     }
     // Second pass: build children maps (inverted from resolvedParents)
     for (const node of nodes) {
         for (const parentRef of node.resolvedParents) {
+            const { id: parentId, ...edgeFields } = parentRef;
+            const edge = { parent: parentId, child: node.id, ...edgeFields };
+            parentEdgesMap.get(node.id).push(edge);
+            if (!childEdgesMap.has(parentId))
+                childEdgesMap.set(parentId, []);
+            childEdgesMap.get(parentId).push(edge);
             // All-edges map
             if (!childrenMap.has(parentRef.id))
                 childrenMap.set(parentRef.id, []);
@@ -78,7 +88,21 @@ export function buildSpaceGraph(nodes, hierarchy) {
         nonHierarchy,
         hierarchyChildren: hierarchyChildrenMap,
         children: childrenMap,
+        parentEdges: parentEdgesMap,
+        childEdges: childEdgesMap,
         hierarchyIds,
         hierarchy,
     };
 }
+/** Resolve a hierarchy by name, or the main hierarchy when no name is given. */
+export function selectHierarchy(metadata, name) {
+    if (name === undefined)
+        return metadata.hierarchy;
+    const hierarchies = metadata.hierarchies ?? [];
+    const hierarchy = hierarchies.find((h) => h.name === name);
+    if (!hierarchy) {
+        const available = hierarchies.map((h) => h.name).join(', ');
+        throw new Error(`Unknown hierarchy: "${name}".${available ? ` Available: ${available}` : ' The schema defines no hierarchies.'}`);
+    }
+    return hierarchy;
+}

package/dist/testing.js

@@ -3,12 +3,12 @@
  * Override any field to represent specific edge contexts.
  */
 export const makeParentRef = (id, overrides = {}) => {
-    const source = overrides.source ?? 'hierarchy';
+    const kind = overrides.kind ?? 'hierarchy';
     return {
         id: id,
         field: 'parent',
-        source,
-        ...(source === 'hierarchy' ? { hierarchy: 'main' } : {}),
+        kind,
+        ...(kind === 'hierarchy' ? { hierarchy: 'main' } : {}),
         selfRef: false,
         fieldOn: 'child',
         ...overrides,

package/dist/types.d.ts

@@ -43,8 +43,8 @@ export type ResolvedParentRef = {
     /** The field name that contained the wikilink (e.g. 'parent', 'key_activities', 'produces_data'). */
     field: string;
     /** Whether this edge originates from a hierarchy level or a relationship definition. */
-    source: 'hierarchy' | 'relationship';
-    /** Name of the hierarchy the edge belongs to. Set only when source is 'hierarchy'. */
+    kind: 'hierarchy' | 'relationship';
+    /** Name of the hierarchy the edge belongs to. Set only when kind is 'hierarchy'. */
     hierarchy?: string;
     /** Whether the parent and child are the same node type (self-referential edge). */
     selfRef: boolean;

package/docs/concepts.md

@@ -319,11 +319,15 @@ Each entry is a `ResolvedParentRef` object:
 |---|---|---|
 | `id` | `NodeId` | The parent node's `id` |
 | `field` | `string` | The frontmatter field that held the wikilink |
-| `source` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy level or a relationship |
-| `hierarchy` | `string` | Name of the hierarchy the edge belongs to; present only when `source` is `'hierarchy'` |
+| `kind` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy level or a relationship |
+| `hierarchy` | `string` | Name of the hierarchy the edge belongs to; present only when `kind` is `'hierarchy'` |
 | `selfRef` | `boolean` | Whether the edge is a same-type (self-referential) parent link |
 
-The `source` and `hierarchy` labels let downstream consumers distinguish edge types and hierarchies without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks within their own hierarchy (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set.
+The `kind` and `hierarchy` labels let downstream consumers distinguish edge types and hierarchies without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks within their own hierarchy (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set.
+
+### Space graph format
+
+The **space graph format** is a space's nodes and hierarchies as plain JSON. A program exports it on one side of a process or network boundary and builds a `SpaceGraph` from it on the other. See [api.md](api.md#space-graph-format).
 
 ### Content links
 
@@ -386,7 +390,7 @@ Each entry in `ancestors[]` or `descendants[]` includes all schema fields of the
 | Metadata field | Type | Description |
 |----------------|------|-------------|
 | `_field` | `string` | The edge field name that connects to this ancestor/descendant |
-| `_source` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy or a relationship |
+| `_kind` | `'hierarchy' \| 'relationship'` | Whether the edge came from a hierarchy or a relationship |
 | `_hierarchy` | `string` | Hierarchy name; present only for hierarchy edges |
 | `_selfRef` | `boolean` | Whether the edge is a same-type (self-referential) link |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",
@@ -22,6 +22,10 @@
       "types": "./dist/api.d.ts",
       "default": "./dist/api.js"
     },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
     "./types": {
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"

package/schemas/generated/space-graph/1.json

@@ -0,0 +1,216 @@
+{
+  "$id": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/space-graph/1.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "structured-context space graph",
+  "type": "object",
+  "properties": {
+    "formatVersion": {
+      "const": 1
+    },
+    "hierarchies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "levels": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string"
+                },
+                "field": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "fieldOn": {
+                  "enum": ["child", "parent"]
+                },
+                "multiple": {
+                  "type": "boolean"
+                },
+                "templateFormat": {
+                  "enum": ["heading", "list", "table", "page"]
+                },
+                "matchers": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "minItems": 1
+                },
+                "embeddedTemplateFields": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "selfRef": {
+                  "type": "boolean"
+                },
+                "selfRefField": {
+                  "type": "string"
+                }
+              },
+              "required": ["type", "field", "fieldOn", "multiple", "selfRef"],
+              "additionalProperties": false
+            }
+          },
+          "allowSkipLevels": {
+            "type": "boolean"
+          }
+        },
+        "required": ["name", "levels"],
+        "additionalProperties": false
+      }
+    },
+    "mainHierarchy": {
+      "type": "string"
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "schemaData": {
+            "type": "object"
+          },
+          "linkTargets": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "type": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          },
+          "contentLinks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "text": {
+                  "type": "string"
+                },
+                "target": {
+                  "type": "string"
+                },
+                "action": {
+                  "enum": ["link", "embed"]
+                },
+                "anchor": {
+                  "type": "string"
+                },
+                "linkSyntax": {
+                  "enum": ["wikilink", "markdown"]
+                }
+              },
+              "required": ["text", "target", "action", "linkSyntax"],
+              "additionalProperties": false
+            }
+          },
+          "source": {
+            "type": "object",
+            "properties": {
+              "file": {
+                "type": "string"
+              },
+              "line": {
+                "type": "integer"
+              },
+              "column": {
+                "type": "integer"
+              }
+            },
+            "required": ["file"],
+            "additionalProperties": false
+          },
+          "resolvedType": {
+            "type": "string"
+          },
+          "resolvedParents": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "field": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": ["hierarchy", "relationship"]
+                },
+                "hierarchy": {
+                  "type": "string"
+                },
+                "selfRef": {
+                  "type": "boolean"
+                },
+                "fieldOn": {
+                  "enum": ["child", "parent"]
+                }
+              },
+              "required": ["id", "field", "kind", "selfRef", "fieldOn"],
+              "additionalProperties": false
+            }
+          },
+          "resolvedLinks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "text": {
+                  "type": "string"
+                },
+                "target": {
+                  "type": "string"
+                },
+                "action": {
+                  "enum": ["link", "embed"]
+                },
+                "anchor": {
+                  "type": "string"
+                },
+                "location": {
+                  "enum": ["node", "internal", "external", "system", "protocol"]
+                }
+              },
+              "required": ["text", "target", "action", "location"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "schemaData",
+          "linkTargets",
+          "type",
+          "resolvedType",
+          "resolvedParents",
+          "resolvedLinks"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["formatVersion", "hierarchies", "nodes"],
+  "additionalProperties": false
+}

package/schemas/generated/space-graph/latest.json

@@ -0,0 +1,216 @@
+{
+  "$id": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/space-graph/1.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "structured-context space graph",
+  "type": "object",
+  "properties": {
+    "formatVersion": {
+      "const": 1
+    },
+    "hierarchies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "levels": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string"
+                },
+                "field": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "fieldOn": {
+                  "enum": ["child", "parent"]
+                },
+                "multiple": {
+                  "type": "boolean"
+                },
+                "templateFormat": {
+                  "enum": ["heading", "list", "table", "page"]
+                },
+                "matchers": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "minItems": 1
+                },
+                "embeddedTemplateFields": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "selfRef": {
+                  "type": "boolean"
+                },
+                "selfRefField": {
+                  "type": "string"
+                }
+              },
+              "required": ["type", "field", "fieldOn", "multiple", "selfRef"],
+              "additionalProperties": false
+            }
+          },
+          "allowSkipLevels": {
+            "type": "boolean"
+          }
+        },
+        "required": ["name", "levels"],
+        "additionalProperties": false
+      }
+    },
+    "mainHierarchy": {
+      "type": "string"
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "schemaData": {
+            "type": "object"
+          },
+          "linkTargets": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "type": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          },
+          "contentLinks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "text": {
+                  "type": "string"
+                },
+                "target": {
+                  "type": "string"
+                },
+                "action": {
+                  "enum": ["link", "embed"]
+                },
+                "anchor": {
+                  "type": "string"
+                },
+                "linkSyntax": {
+                  "enum": ["wikilink", "markdown"]
+                }
+              },
+              "required": ["text", "target", "action", "linkSyntax"],
+              "additionalProperties": false
+            }
+          },
+          "source": {
+            "type": "object",
+            "properties": {
+              "file": {
+                "type": "string"
+              },
+              "line": {
+                "type": "integer"
+              },
+              "column": {
+                "type": "integer"
+              }
+            },
+            "required": ["file"],
+            "additionalProperties": false
+          },
+          "resolvedType": {
+            "type": "string"
+          },
+          "resolvedParents": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "field": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": ["hierarchy", "relationship"]
+                },
+                "hierarchy": {
+                  "type": "string"
+                },
+                "selfRef": {
+                  "type": "boolean"
+                },
+                "fieldOn": {
+                  "enum": ["child", "parent"]
+                }
+              },
+              "required": ["id", "field", "kind", "selfRef", "fieldOn"],
+              "additionalProperties": false
+            }
+          },
+          "resolvedLinks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "text": {
+                  "type": "string"
+                },
+                "target": {
+                  "type": "string"
+                },
+                "action": {
+                  "enum": ["link", "embed"]
+                },
+                "anchor": {
+                  "type": "string"
+                },
+                "location": {
+                  "enum": ["node", "internal", "external", "system", "protocol"]
+                }
+              },
+              "required": ["text", "target", "action", "location"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "schemaData",
+          "linkTargets",
+          "type",
+          "resolvedType",
+          "resolvedParents",
+          "resolvedLinks"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["formatVersion", "hierarchies", "nodes"],
+  "additionalProperties": false
+}