structured-context 0.9.0

package/dist/schemas/generated/_structured_context_schema_meta.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "title": "structured-context schema dialect",
+  "description": "Extends JSON Schema Draft-07 with top-level $metadata for hierarchy and rule metadata.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "http://json-schema.org/draft-07/schema#"
+    }
+  ],
+  "properties": {
+    "$metadata": {
+      "type": "object",
+      "properties": {
+        "hierarchy": {
+          "type": "object",
+          "properties": {
+            "levels": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "oneOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "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",
+                        "minLength": 1
+                      }
+                    },
+                    "required": ["type"],
+                    "additionalProperties": false
+                  }
+                ]
+              }
+            },
+            "allowSkipLevels": {
+              "type": "boolean"
+            }
+          },
+          "required": ["levels"],
+          "additionalProperties": false
+        },
+        "relationships": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "parent": {
+                "type": "string",
+                "minLength": 1
+              },
+              "type": {
+                "type": "string",
+                "minLength": 1
+              },
+              "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
+                }
+              }
+            },
+            "required": ["parent", "type"],
+            "additionalProperties": false
+          }
+        },
+        "aliases": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "category": {
+                    "enum": ["validation", "coherence", "workflow", "best-practice"]
+                  },
+                  "description": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "check": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "type": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "scope": {
+                    "enum": ["global"]
+                  },
+                  "override": {
+                    "type": "boolean"
+                  }
+                },
+                "required": ["id", "category", "description", "check"],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "$ref": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": ["$ref"],
+                "additionalProperties": false
+              }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/dist/schemas/knowledge_wiki.json

@@ -0,0 +1,206 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "$id": "sctx://knowledge_wiki",
+  "title": "Knowledge Wiki",
+  "description": "Lightweight schema for LLM-maintained knowledge wikis. Supports source pages, concept pages, syntheses, and notes. Designed for compounding knowledge bases where the LLM creates and maintains wiki pages from raw sources.\n\nFlat entity model — no hierarchy, no required parent links. Wikilinks between any pages are valid for arbitrary cross-referencing. The schema validates structure and provenance; it does not constrain meaning.\n\nBased on the pattern described in Karpathy's LLM Wiki (2026).",
+  "$metadata": {
+    "aliases": {
+      "source_summary": "source",
+      "study": "source",
+      "article": "source",
+      "paper": "source",
+      "research": "source"
+    },
+    "relationships": [
+      {
+        "parent": "source",
+        "type": "source",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "source",
+        "type": "synthesis",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "concept",
+        "type": "synthesis",
+        "field": "concepts",
+        "fieldOn": "child",
+        "multiple": true
+      }
+    ],
+    "rules": [
+      {
+        "id": "synthesis-references-sources",
+        "category": "coherence",
+        "description": "Syntheses should reference at least one contributing source in their sources array",
+        "type": "synthesis",
+        "check": "$exists(current.sources) and $count(current.sources) >= 1"
+      },
+      {
+        "id": "concept-has-summary",
+        "category": "best-practice",
+        "description": "Concept pages should have a short summary for index discoverability",
+        "type": "concept",
+        "check": "$exists(current.summary) and $length(current.summary) > 0"
+      }
+    ]
+  },
+  "oneOf": [
+    {
+      "type": "object",
+      "description": "A processed summary of a raw source (article, paper, book, video, thread, podcast, etc.). Captures key information from the source in structured form with provenance.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "source" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "url": {
+          "type": "string",
+          "description": "URL of the original source"
+        },
+        "local_copy": {
+          "$ref": "sctx://_sctx_base#/$defs/wikilink",
+          "description": "Wikilink to a local copy of the source (e.g. a saved PDF or clipped note)"
+        },
+        "author": {
+          "type": "string",
+          "description": "Author or creator of the source"
+        },
+        "book": {
+          "type": "string",
+          "description": "Book title and author if the source is a book"
+        },
+        "published_date": {
+          "type": "string",
+          "format": "date",
+          "description": "Original publication date"
+        },
+        "source_type": {
+          "type": "string",
+          "description": "Kind of source material. Free-form — common values include article, paper, book, video, podcast, thread, substack, tweet, website. Not enum-constrained to allow evolving vocabulary."
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to other source pages that this one references or extends"
+        }
+      },
+      "required": ["type", "url"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "source",
+          "author": "Joe Bloggs",
+          "url": "https://example.com/design-of-yesterday-things",
+          "source_type": "book",
+          "tags": ["design", "ux", "psychology"]
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "description": "A concept or entity page — defines and frames a specific idea, mechanism, or domain term. May draw from multiple sources. The building blocks of the wiki's knowledge graph.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "concept" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to source pages that contributed to this concept"
+        },
+        "related": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to related concept or synthesis pages"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "concept",
+          "summary": "A property of an object that signals how it can be used, first described by Gibson and popularised in design by Norman",
+          "tags": ["design", "ux"]
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "description": "A synthesis page — connects multiple concepts and sources into a coherent model, framework, or thesis. The highest-value pages in a knowledge wiki. Must reference contributing sources.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "synthesis" },
+        "summary": {
+          "$ref": "sctx://_sctx_base#/$defs/summary"
+        },
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to source pages this synthesis draws from"
+        },
+        "concepts": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to concept pages this synthesis connects"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "synthesis",
+          "summary": "How Norman's affordance model and feedback principles combine to explain intuitive vs confusing interfaces",
+          "sources": ["[[The Design of Everyday Things - Don Norman]]"],
+          "concepts": ["[[Affordance]]", "[[Feedback loop]]"]
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "description": "Personal notes, journal entries, appointments, experiential records. Your own data about your journey — not sourced from external material.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "note" },
+        "date": {
+          "type": "string",
+          "format": "date",
+          "description": "Date this entry was created or relates to"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "note",
+          "date": "2024-03-15",
+          "tags": ["reading-log"]
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "description": "The wiki index — a catalog of all pages with links, summaries, and metadata. Updated by the agent on ingest. Used as the primary navigation entry point.",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "index" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "index"
+        }
+      ]
+    }
+  ]
+}

package/dist/schemas/strict_ost.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "$id": "sctx://strict_ost",
+  "title": "Opportunity Solution Tree (Strict)",
+  // Follows Teresa Torres' 4-level OST structure as described in "Continuous Discovery Habits" (2021)
+  // and at producttalk.org.
+  // Structure: outcome → opportunity → solution → assumption test
+  "description": "Validates frontmatter for space node files following the canonical 4-level OST structure: outcome → opportunity → solution → assumption test",
+  "oneOf": [
+    {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" },
+        { "$ref": "sctx://_ost_strict#/$defs/outcomeProps" }
+      ],
+      "properties": {
+        "type": { "const": "outcome" }
+      },
+      "required": ["type"],
+      "not": { "required": ["parent"] },
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "outcome",
+          "status": "active",
+          "metric": "Increase % of first-time users who reach the aha moment"
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" },
+        { "$ref": "sctx://_ost_strict#/$defs/opportunityProps" }
+      ],
+      "properties": {
+        "type": { "const": "opportunity" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "opportunity",
+          "status": "active",
+          "parent": "[[Increase Trial Conversion]]",
+          "source": "Interview with Sarah, 2024-02-10 - mentioned she drops off during signup"
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "solution" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "solution",
+          "status": "identified",
+          "parent": "[[Simplify Signup Flow]]"
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" },
+        { "$ref": "sctx://_ost_strict#/$defs/assumptionTestProps" }
+      ],
+      "properties": {
+        "type": { "const": "assumption_test" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "assumption_test",
+          "status": "exploring",
+          "parent": "[[Simplify Signup Flow]]",
+          "assumption": "Users can complete the simplified signup in under 2 minutes",
+          "category": "usability"
+        }
+      ]
+    }
+  ]
+}

package/dist/space-graph.d.ts

@@ -0,0 +1,28 @@
+import type { HierarchyLevel, SpaceNode } from './types';
+/**
+ * A navigable graph over a set of SpaceNodes.
+ *
+ * Built once from SpaceNode[] + hierarchy levels via buildSpaceGraph().
+ * Provides typed access to nodes, edges, traversal, and classification
+ * so consumers don't need to build their own indexes.
+ */
+export type SpaceGraph = {
+    /** All nodes, keyed by title. Preserves insertion order. */
+    readonly nodes: ReadonlyMap<string, SpaceNode>;
+    /** Hierarchy roots: nodes of the root type with no valid hierarchy parents. */
+    readonly hierarchyRoots: readonly SpaceNode[];
+    /** Orphans: hierarchy-typed nodes with no valid hierarchy parents in the node set. */
+    readonly orphans: readonly SpaceNode[];
+    /** Non-hierarchy nodes: type not in the hierarchy levels definition. */
+    readonly nonHierarchy: readonly SpaceNode[];
+    /** Hierarchy children map: parent title → direct children connected via hierarchy edges only. */
+    readonly hierarchyChildren: ReadonlyMap<string, readonly SpaceNode[]>;
+    /** All-edges children map: parent title → direct children connected via any edge (hierarchy + relationship). */
+    readonly children: ReadonlyMap<string, readonly SpaceNode[]>;
+    /** Set of all node titles that are part of the hierarchy (roots + their descendants + orphans). */
+    readonly hierarchyTitles: ReadonlySet<string>;
+    /** Hierarchy levels used to build this graph. */
+    readonly levels: readonly HierarchyLevel[];
+};
+/** Build a SpaceGraph from a flat list of SpaceNodes and hierarchy level definitions. */
+export declare function buildSpaceGraph(nodes: SpaceNode[], levels: readonly HierarchyLevel[]): SpaceGraph;

package/dist/space-graph.js

@@ -0,0 +1,82 @@
+/** Build a SpaceGraph from a flat list of SpaceNodes and hierarchy level definitions. */
+export function buildSpaceGraph(nodes, levels) {
+    const hierarchyTypes = new Set(levels.map((l) => l.type));
+    const rootType = levels[0]?.type;
+    const nodesMap = new Map();
+    const hierarchyChildrenMap = new Map();
+    const childrenMap = new Map();
+    const hierarchyRoots = [];
+    const orphans = [];
+    const nonHierarchy = [];
+    // First pass: register all nodes and init adjacency lists
+    for (const node of nodes) {
+        nodesMap.set(node.title, node);
+        hierarchyChildrenMap.set(node.title, []);
+        childrenMap.set(node.title, []);
+    }
+    // Second pass: build children maps (inverted from resolvedParents)
+    for (const node of nodes) {
+        for (const parentRef of node.resolvedParents) {
+            // All-edges map
+            if (!childrenMap.has(parentRef.title))
+                childrenMap.set(parentRef.title, []);
+            childrenMap.get(parentRef.title).push(node);
+            // Hierarchy-only map
+            if (parentRef.source === 'hierarchy') {
+                if (!hierarchyChildrenMap.has(parentRef.title))
+                    hierarchyChildrenMap.set(parentRef.title, []);
+                hierarchyChildrenMap.get(parentRef.title).push(node);
+            }
+        }
+    }
+    // Third pass: classify each node
+    for (const node of nodes) {
+        const nodeType = node.resolvedType;
+        if (!hierarchyTypes.has(nodeType)) {
+            nonHierarchy.push(node);
+            continue;
+        }
+        // Only hierarchy-sourced parents determine structural position in the DAG
+        const hierarchyParents = node.resolvedParents.filter((r) => r.source === 'hierarchy');
+        if (hierarchyParents.length === 0) {
+            if (nodeType === rootType) {
+                hierarchyRoots.push(node);
+            }
+            else {
+                orphans.push(node);
+            }
+        }
+        else {
+            // Check if at least one hierarchy parent is actually in the node set
+            const hasValidParent = hierarchyParents.some((r) => nodesMap.has(r.title));
+            if (!hasValidParent) {
+                // All hierarchy parents are dangling — treat as orphan
+                orphans.push(node);
+            }
+        }
+    }
+    // Build hierarchyTitles: BFS from roots + orphans through hierarchyChildren
+    const hierarchyTitles = new Set();
+    function addHierarchySubtree(node) {
+        if (hierarchyTitles.has(node.title))
+            return;
+        hierarchyTitles.add(node.title);
+        for (const child of hierarchyChildrenMap.get(node.title) ?? []) {
+            addHierarchySubtree(child);
+        }
+    }
+    for (const root of hierarchyRoots)
+        addHierarchySubtree(root);
+    for (const orphan of orphans)
+        addHierarchySubtree(orphan);
+    return {
+        nodes: nodesMap,
+        hierarchyRoots,
+        orphans,
+        nonHierarchy,
+        hierarchyChildren: hierarchyChildrenMap,
+        children: childrenMap,
+        hierarchyTitles,
+        levels,
+    };
+}