structured-context 0.16.0 → 0.17.1

package/dist/space-graph-data.d.ts

@@ -0,0 +1,237 @@
+import { type SpaceGraph } from './space-graph';
+import type { Hierarchy, SchemaMetadata, SpaceNode } from './types';
+/** Bump when the shape of SpaceGraphData changes; the generator refuses to overwrite a released version's schema. */
+export declare const SPACE_GRAPH_FORMAT_VERSION = 1;
+/** Folder under `schemas/generated/` holding the format schema: `latest.json` and one frozen file per released version. */
+export declare const SPACE_GRAPH_SCHEMA_DIR = "space-graph";
+/** Schema `$id` for a format version file, e.g. `.../generated/space-graph/1.json`. */
+export declare function spaceGraphSchemaId(file: string): string;
+/** JSON Schema for SpaceGraphData. Written to `schemas/generated/space-graph/` by `bun run generate:schema-meta`. */
+export declare const SPACE_GRAPH_DATA_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "structured-context space graph";
+    readonly type: "object";
+    readonly properties: {
+        readonly formatVersion: {
+            readonly const: 1;
+        };
+        readonly hierarchies: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly levels: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly selfRef: {
+                                    readonly type: "boolean";
+                                };
+                                readonly selfRefField: {
+                                    readonly type: "string";
+                                };
+                                readonly templateFormat: {
+                                    readonly enum: readonly ["heading", "list", "table", "page"];
+                                };
+                                readonly matchers: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly minItems: 1;
+                                };
+                                readonly embeddedTemplateFields: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly field: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly fieldOn: {
+                                    readonly enum: readonly ["child", "parent"];
+                                };
+                                readonly multiple: {
+                                    readonly type: "boolean";
+                                };
+                                readonly type: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["type", "field", "fieldOn", "multiple", "selfRef"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                    readonly allowSkipLevels: {
+                        readonly type: "boolean";
+                    };
+                };
+                readonly required: readonly ["name", "levels"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly mainHierarchy: {
+            readonly type: "string";
+        };
+        readonly nodes: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly schemaData: {
+                        readonly type: "object";
+                    };
+                    readonly linkTargets: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly type: {
+                        readonly type: "string";
+                    };
+                    readonly content: {
+                        readonly type: "string";
+                    };
+                    readonly contentLinks: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly linkSyntax: {
+                                    readonly enum: readonly ["wikilink", "markdown"];
+                                };
+                                readonly text: {
+                                    readonly type: "string";
+                                };
+                                readonly target: {
+                                    readonly type: "string";
+                                };
+                                readonly action: {
+                                    readonly enum: readonly ["link", "embed"];
+                                };
+                                readonly anchor: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["text", "target", "action", "linkSyntax"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                    readonly source: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly file: {
+                                readonly type: "string";
+                            };
+                            readonly line: {
+                                readonly type: "integer";
+                            };
+                            readonly column: {
+                                readonly type: "integer";
+                            };
+                        };
+                        readonly required: readonly ["file"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly resolvedType: {
+                        readonly type: "string";
+                    };
+                    readonly resolvedParents: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                };
+                                readonly field: {
+                                    readonly type: "string";
+                                };
+                                readonly kind: {
+                                    readonly enum: readonly ["hierarchy", "relationship"];
+                                };
+                                readonly hierarchy: {
+                                    readonly type: "string";
+                                };
+                                readonly selfRef: {
+                                    readonly type: "boolean";
+                                };
+                                readonly fieldOn: {
+                                    readonly enum: readonly ["child", "parent"];
+                                };
+                            };
+                            readonly required: readonly ["id", "field", "kind", "selfRef", "fieldOn"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                    readonly resolvedLinks: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly location: {
+                                    readonly enum: readonly ["node", "internal", "external", "system", "protocol"];
+                                };
+                                readonly text: {
+                                    readonly type: "string";
+                                };
+                                readonly target: {
+                                    readonly type: "string";
+                                };
+                                readonly action: {
+                                    readonly enum: readonly ["link", "embed"];
+                                };
+                                readonly anchor: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["text", "target", "action", "location"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                };
+                readonly required: readonly ["id", "title", "schemaData", "linkTargets", "type", "resolvedType", "resolvedParents", "resolvedLinks"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly required: readonly ["formatVersion", "hierarchies", "nodes"];
+    readonly additionalProperties: false;
+};
+/**
+ * A space's nodes and hierarchies as plain JSON, for passing a graph across a process or network boundary.
+ *
+ * Edges live in each node's resolvedParents, including edges to nodes outside the set. The format names every
+ * hierarchy, so the receiver picks which one structures the graph.
+ */
+export type SpaceGraphData = {
+    formatVersion: typeof SPACE_GRAPH_FORMAT_VERSION;
+    hierarchies: Hierarchy[];
+    /** Name of the main hierarchy, if the schema has one. */
+    mainHierarchy?: string;
+    nodes: SpaceNode[];
+};
+/** Turn a set of nodes and its schema's hierarchies into SpaceGraphData. Pass `graph.nodes.values()` for a filtered graph. */
+export declare function exportSpaceGraph(nodes: Iterable<SpaceNode>, metadata: Pick<SchemaMetadata, 'hierarchy' | 'hierarchies'>): SpaceGraphData;
+/**
+ * Build a SpaceGraph from SpaceGraphData, structured by the named hierarchy (default: the main hierarchy).
+ * Throws on an unsupported format version or an unknown hierarchy name.
+ */
+export declare function spaceGraphFrom(data: SpaceGraphData, options?: {
+    hierarchy?: string;
+}): SpaceGraph;

package/dist/space-graph-data.js

@@ -0,0 +1,129 @@
+import { EDGE_PROPS, EMBEDDING_PROPS, SCHEMA_META_BASE_URL } from './schema/metadata-contract';
+import { buildSpaceGraph, selectHierarchy } from './space-graph';
+/** Bump when the shape of SpaceGraphData changes; the generator refuses to overwrite a released version's schema. */
+export const SPACE_GRAPH_FORMAT_VERSION = 1;
+/** Folder under `schemas/generated/` holding the format schema: `latest.json` and one frozen file per released version. */
+export const SPACE_GRAPH_SCHEMA_DIR = 'space-graph';
+/** Schema `$id` for a format version file, e.g. `.../generated/space-graph/1.json`. */
+export function spaceGraphSchemaId(file) {
+    return `${SCHEMA_META_BASE_URL}/${SPACE_GRAPH_SCHEMA_DIR}/${file}.json`;
+}
+const STRING = { type: 'string' };
+const SOURCE_LOCATION_SCHEMA = {
+    type: 'object',
+    properties: { file: STRING, line: { type: 'integer' }, column: { type: 'integer' } },
+    required: ['file'],
+    additionalProperties: false,
+};
+const CONTENT_LINK_PROPS = {
+    text: STRING,
+    target: STRING,
+    action: { enum: ['link', 'embed'] },
+    anchor: STRING,
+};
+const CONTENT_LINK_SCHEMA = {
+    type: 'object',
+    properties: { ...CONTENT_LINK_PROPS, linkSyntax: { enum: ['wikilink', 'markdown'] } },
+    required: ['text', 'target', 'action', 'linkSyntax'],
+    additionalProperties: false,
+};
+const RESOLVED_CONTENT_LINK_SCHEMA = {
+    type: 'object',
+    properties: { ...CONTENT_LINK_PROPS, location: { enum: ['node', 'internal', 'external', 'system', 'protocol'] } },
+    required: ['text', 'target', 'action', 'location'],
+    additionalProperties: false,
+};
+const RESOLVED_PARENT_REF_SCHEMA = {
+    type: 'object',
+    properties: {
+        id: STRING,
+        field: STRING,
+        kind: { enum: ['hierarchy', 'relationship'] },
+        hierarchy: STRING,
+        selfRef: { type: 'boolean' },
+        fieldOn: EDGE_PROPS.fieldOn,
+    },
+    required: ['id', 'field', 'kind', 'selfRef', 'fieldOn'],
+    additionalProperties: false,
+};
+const SPACE_NODE_SCHEMA = {
+    type: 'object',
+    properties: {
+        id: STRING,
+        title: STRING,
+        schemaData: { type: 'object' },
+        linkTargets: { type: 'array', items: STRING },
+        type: STRING,
+        content: STRING,
+        contentLinks: { type: 'array', items: CONTENT_LINK_SCHEMA },
+        source: SOURCE_LOCATION_SCHEMA,
+        resolvedType: STRING,
+        resolvedParents: { type: 'array', items: RESOLVED_PARENT_REF_SCHEMA },
+        resolvedLinks: { type: 'array', items: RESOLVED_CONTENT_LINK_SCHEMA },
+    },
+    required: ['id', 'title', 'schemaData', 'linkTargets', 'type', 'resolvedType', 'resolvedParents', 'resolvedLinks'],
+    additionalProperties: false,
+};
+/** A hierarchy level after normalisation: edge fields are always present. */
+const HIERARCHY_LEVEL_SCHEMA = {
+    type: 'object',
+    properties: {
+        type: STRING,
+        ...EDGE_PROPS,
+        ...EMBEDDING_PROPS,
+        selfRef: { type: 'boolean' },
+        selfRefField: STRING,
+    },
+    required: ['type', 'field', 'fieldOn', 'multiple', 'selfRef'],
+    additionalProperties: false,
+};
+const HIERARCHY_SCHEMA = {
+    type: 'object',
+    properties: {
+        name: STRING,
+        levels: { type: 'array', items: HIERARCHY_LEVEL_SCHEMA },
+        allowSkipLevels: { type: 'boolean' },
+    },
+    required: ['name', 'levels'],
+    additionalProperties: false,
+};
+/** JSON Schema for SpaceGraphData. Written to `schemas/generated/space-graph/` by `bun run generate:schema-meta`. */
+export const SPACE_GRAPH_DATA_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'structured-context space graph',
+    type: 'object',
+    properties: {
+        formatVersion: { const: SPACE_GRAPH_FORMAT_VERSION },
+        hierarchies: { type: 'array', items: HIERARCHY_SCHEMA },
+        mainHierarchy: STRING,
+        nodes: { type: 'array', items: SPACE_NODE_SCHEMA },
+    },
+    required: ['formatVersion', 'hierarchies', 'nodes'],
+    additionalProperties: false,
+};
+/** Turn a set of nodes and its schema's hierarchies into SpaceGraphData. Pass `graph.nodes.values()` for a filtered graph. */
+export function exportSpaceGraph(nodes, metadata) {
+    return {
+        formatVersion: SPACE_GRAPH_FORMAT_VERSION,
+        hierarchies: metadata.hierarchies ?? [],
+        ...(metadata.hierarchy ? { mainHierarchy: metadata.hierarchy.name } : {}),
+        nodes: [...nodes],
+    };
+}
+/**
+ * Build a SpaceGraph from SpaceGraphData, structured by the named hierarchy (default: the main hierarchy).
+ * Throws on an unsupported format version or an unknown hierarchy name.
+ */
+export function spaceGraphFrom(data, options = {}) {
+    if (data.formatVersion !== SPACE_GRAPH_FORMAT_VERSION) {
+        throw new Error(`Unsupported space graph format version ${data.formatVersion}; expected ${SPACE_GRAPH_FORMAT_VERSION}.`);
+    }
+    const metadata = {
+        hierarchy: data.hierarchies.find((h) => h.name === data.mainHierarchy),
+        hierarchies: data.hierarchies,
+    };
+    return buildSpaceGraph(data.nodes, selectHierarchy(metadata, options.hierarchy));
+}
+// Fails typecheck when SPACE_GRAPH_DATA_SCHEMA and SpaceGraphData drift apart.
+const _schemaMatchesType = true;
+void _schemaMatchesType;

package/dist/space-graph.d.ts

@@ -1,4 +1,9 @@
-import type { Hierarchy, NodeId, SpaceNode } from './types';
+import type { Hierarchy, NodeId, ResolvedParentRef, SchemaMetadata, SpaceNode } from './types';
+/** A typed edge between two nodes: a node's resolvedParents entry, with both ends named. */
+export type SpaceEdge = Omit<ResolvedParentRef, 'id'> & {
+    parent: NodeId;
+    child: NodeId;
+};
 /**
  * A navigable graph over a set of SpaceNodes.
  *
@@ -21,6 +26,10 @@ export type SpaceGraph = {
     readonly hierarchyChildren: ReadonlyMap<NodeId, readonly SpaceNode[]>;
     /** All-edges children map: parent id → direct children connected via any edge (hierarchy + relationship). */
     readonly children: ReadonlyMap<NodeId, readonly SpaceNode[]>;
+    /** Parent edges: child id → edges to its parents (hierarchy + relationship), in resolvedParents order. */
+    readonly parentEdges: ReadonlyMap<NodeId, readonly SpaceEdge[]>;
+    /** Child edges: parent id → edges to its children (hierarchy + relationship). */
+    readonly childEdges: ReadonlyMap<NodeId, readonly SpaceEdge[]>;
     /** Set of all node ids that are part of the hierarchy (roots + their descendants + orphans). */
     readonly hierarchyIds: ReadonlySet<NodeId>;
     /** The hierarchy used to build this graph, if the schema has one. */
@@ -28,3 +37,5 @@ export type SpaceGraph = {
 };
 /** Build a SpaceGraph from a flat list of SpaceNodes and the hierarchy to structure it by. */
 export declare function buildSpaceGraph(nodes: SpaceNode[], hierarchy: Hierarchy | undefined): SpaceGraph;
+/** Resolve a hierarchy by name, or the main hierarchy when no name is given. */
+export declare function selectHierarchy(metadata: Pick<SchemaMetadata, 'hierarchy' | 'hierarchies'>, name: string | undefined): Hierarchy | undefined;

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.16.0",
+  "version": "0.17.1",
   "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"
@@ -57,7 +61,6 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.310",
     "@biomejs/biome": "^2.5.15",
     "@types/bun": "^1.4.4",
-    "json-schema-to-ts": "^3.1.1",
     "lefthook": "^2.2.2"
   },
   "peerDependencies": {
@@ -70,6 +73,7 @@
     "fast-glob": "^3.3.3",
     "gray-matter": "^4.0.3",
     "js-yaml": "^5.4.3",
+    "json-schema-to-ts": "^3.1.1",
     "json5": "^2.2.3",
     "jsonata": "^2.2.1",
     "mdast-util-to-string": "^4.0.0",