structured-context 0.10.0 → 0.12.0

package/dist/schema/validate-graph.js

@@ -4,14 +4,19 @@ import { resolveNodeType } from '../schema/schema';
  * Assumes resolveGraphEdges has already been called to populate node.resolvedParents.
  */
 export function validateGraph(nodes, metadata, unresolvedRefs = []) {
-    const refErrors = unresolvedRefs.map((u) => ({ file: u.label, parent: u.ref, error: u.message }));
+    const refErrors = unresolvedRefs.map((u) => ({
+        file: u.source?.file ?? u.label,
+        ...(u.source?.line !== undefined ? { line: u.source.line } : {}),
+        parent: u.ref,
+        error: u.message,
+    }));
     const violations = validateHierarchyStructure(nodes, metadata);
     return { violations, refErrors };
 }
 /**
  * Validate that resolved parents follow hierarchy level rules and relationship type constraints.
  *
- * For hierarchy edges (fieldOn:'child', source:'hierarchy'): validates level ordering.
+ * For hierarchy edges (fieldOn:'child', source:'hierarchy'): validates level ordering within the edge's hierarchy.
  * For relationship edges (fieldOn:'child', source:'relationship'): validates parent type.
  * For fieldOn:'parent' edges: validates child type, violation attributed to the field-owner node.
  *
@@ -19,11 +24,12 @@ export function validateGraph(nodes, metadata, unresolvedRefs = []) {
  */
 export function validateHierarchyStructure(nodes, metadata) {
     const violations = [];
-    const levels = metadata.hierarchy?.levels ?? [];
+    const hierarchies = metadata.hierarchies ?? [];
     const relationships = metadata.relationships ?? [];
-    const allowSkipLevels = metadata.hierarchy?.allowSkipLevels ?? false;
     const typeAliases = metadata.typeAliases;
-    const hierarchy = levels.map((level) => resolveNodeType(level.type, typeAliases));
+    const hierarchiesByName = new Map(hierarchies.map((h) => [h.name, h]));
+    const levelTypesByName = new Map(hierarchies.map((h) => [h.name, h.levels.map((level) => resolveNodeType(level.type, typeAliases))]));
+    const allHierarchyTypes = new Set([...levelTypesByName.values()].flat());
     // Build type rules: (ownerType, field) → set of valid target types.
     // For fieldOn:'child': owner=childType, target=parentType.
     // For fieldOn:'parent': owner=parentType (field owner), target=childType.
@@ -38,18 +44,20 @@ export function validateHierarchyStructure(nodes, metadata) {
             fieldMap.set(field, new Set());
         fieldMap.get(field).add(target);
     }
-    for (let i = 1; i < levels.length; i++) {
-        const level = levels[i];
-        const parentLevel = levels[i - 1];
-        if (level.fieldOn === 'parent') {
-            addTypeRule(parentLevel.type, level.field, level.type);
-            if (level.selfRef)
-                addTypeRule(level.type, level.field, level.type);
-        }
-        else {
-            addTypeRule(level.type, level.field, parentLevel.type);
-            if (level.selfRef)
-                addTypeRule(level.type, level.field, level.type);
+    for (const { levels } of hierarchies) {
+        for (let i = 1; i < levels.length; i++) {
+            const level = levels[i];
+            const parentLevel = levels[i - 1];
+            if (level.fieldOn === 'parent') {
+                addTypeRule(parentLevel.type, level.field, level.type);
+                if (level.selfRef)
+                    addTypeRule(level.type, level.field, level.type);
+            }
+            else {
+                addTypeRule(level.type, level.field, parentLevel.type);
+                if (level.selfRef)
+                    addTypeRule(level.type, level.field, level.type);
+            }
         }
     }
     for (const rel of relationships) {
@@ -107,15 +115,24 @@ export function validateHierarchyStructure(nodes, metadata) {
                 }
             }
             else {
-                // Hierarchy edge (fieldOn:'child', source:'hierarchy'): validate level ordering.
-                const typeIndex = hierarchy.indexOf(nodeType);
-                const parentIndex = hierarchy.indexOf(parentType);
-                if (typeIndex === -1 || parentIndex === -1)
+                // Hierarchy edge (fieldOn:'child', source:'hierarchy'): validate level ordering within its hierarchy.
+                const edgeHierarchy = parentRef.hierarchy !== undefined ? hierarchiesByName.get(parentRef.hierarchy) : undefined;
+                if (!edgeHierarchy)
+                    continue;
+                const levelTypes = levelTypesByName.get(edgeHierarchy.name);
+                const typeIndex = levelTypes.indexOf(nodeType);
+                const parentIndex = levelTypes.indexOf(parentType);
+                // A parent from another hierarchy is invalid; a parent of a type outside every hierarchy is not checked here.
+                if (typeIndex === -1 || (parentIndex === -1 && !allHierarchyTypes.has(parentType)))
                     continue;
-                const level = levels[typeIndex];
+                const level = edgeHierarchy.levels[typeIndex];
                 const canSelfRef = level.selfRef || level.selfRefField !== undefined;
+                const allowSkipLevels = edgeHierarchy.allowSkipLevels ?? false;
                 let isValidHierarchy = false;
-                if (parentIndex === typeIndex - 1) {
+                if (parentIndex === -1) {
+                    isValidHierarchy = false;
+                }
+                else if (parentIndex === typeIndex - 1) {
                     isValidHierarchy = true;
                 }
                 else if (canSelfRef && parentIndex === typeIndex) {

package/dist/schema/validate-rules.d.ts

@@ -1,4 +1,8 @@
-import type { Rule, RuleViolation, SpaceNode } from '../types';
+import type { Rule, RuleCategory, RuleSeverity, RuleViolation, SpaceNode } from '../types';
+/** Default severity for each rule category. A rule's own `severity` field overrides this. */
+export declare const DEFAULT_SEVERITY_BY_CATEGORY: Record<RuleCategory, RuleSeverity>;
+/** Effective severity of a rule: its explicit `severity`, else its category default. */
+export declare function ruleSeverity(rule: Rule): RuleSeverity;
 /**
  * Validate nodes against rules metadata.
  * Returns a list of rule violations found.

package/dist/schema/validate-rules.js

@@ -1,4 +1,15 @@
 import { buildEvalContext, evaluateExpression } from './evaluate-rule';
+/** Default severity for each rule category. A rule's own `severity` field overrides this. */
+export const DEFAULT_SEVERITY_BY_CATEGORY = {
+    validation: 'error',
+    coherence: 'warning',
+    workflow: 'warning',
+    'best-practice': 'info',
+};
+/** Effective severity of a rule: its explicit `severity`, else its category default. */
+export function ruleSeverity(rule) {
+    return rule.severity ?? DEFAULT_SEVERITY_BY_CATEGORY[rule.category];
+}
 /**
  * Validate nodes against rules metadata.
  * Returns a list of rule violations found.
@@ -19,6 +30,7 @@ export async function validateRules(nodes, rules) {
     }
     // Evaluate each rule against applicable nodes
     for (const rule of rules) {
+        const severity = ruleSeverity(rule);
         if (rule.scope === 'global') {
             // Global rules are evaluated once against the full node set.
             // A sentinel node provides the evaluation context (nodes array is what matters).
@@ -27,7 +39,13 @@ export async function validateRules(nodes, rules) {
                 const context = buildEvalContext(sentinel, nodes, nodeIndex);
                 const result = await evaluateExpression(rule.check, context);
                 if (result !== true) {
-                    violations.push({ file: '', ruleId: rule.id, category: rule.category, description: rule.description });
+                    violations.push({
+                        file: '',
+                        ruleId: rule.id,
+                        category: rule.category,
+                        severity,
+                        description: rule.description,
+                    });
                 }
             }
         }
@@ -41,6 +59,7 @@ export async function validateRules(nodes, rules) {
                         file: node.label,
                         ruleId: rule.id,
                         category: rule.category,
+                        severity,
                         description: rule.description,
                     });
                 }

package/dist/schemas/_knowledge_wiki.json

@@ -1,6 +1,6 @@
 {
-  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
-  "$id": "sctx://_knowledge_wiki",
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json",
+  "$id": "sctx://core/_knowledge_wiki",
   // Shared entity definitions for knowledge wiki schemas.
   // Provides aliases, relationships, rules, and entity type $defs.
   // This partial has no hierarchy — wiki entities are flat with no required parent links.
@@ -65,18 +65,18 @@
     "source": {
       "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" }],
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "source" },
         "summary": {
-          "$ref": "sctx://_sctx_base#/$defs/summary"
+          "$ref": "sctx://core/_sctx_base#/$defs/summary"
         },
         "url": {
           "type": "string",
           "description": "URL of the original source"
         },
         "local_copy": {
-          "$ref": "sctx://_sctx_base#/$defs/wikilink",
+          "$ref": "sctx://core/_sctx_base#/$defs/wikilink",
           "description": "Wikilink to a local copy of the source (e.g. a saved PDF or clipped note)"
         },
         "author": {
@@ -98,7 +98,7 @@
         },
         "sources": {
           "type": "array",
-          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "items": { "$ref": "sctx://core/_sctx_base#/$defs/wikilink" },
           "description": "Wikilinks to other source pages that this one references or extends"
         }
       },
@@ -117,20 +117,20 @@
     "concept": {
       "type": "object",
       "description": "A concept 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" }],
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "concept" },
         "summary": {
-          "$ref": "sctx://_sctx_base#/$defs/summary"
+          "$ref": "sctx://core/_sctx_base#/$defs/summary"
         },
         "sources": {
           "type": "array",
-          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "items": { "$ref": "sctx://core/_sctx_base#/$defs/wikilink" },
           "description": "Wikilinks to source pages that contributed to this concept"
         },
         "related": {
           "type": "array",
-          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "items": { "$ref": "sctx://core/_sctx_base#/$defs/wikilink" },
           "description": "Wikilinks to related concept or synthesis pages"
         }
       },
@@ -147,20 +147,20 @@
     "entity": {
       "type": "object",
       "description": "A concrete entity — a person, organisation, product, model, or other named thing. The building blocks of the wiki's knowledge graph alongside concepts. Entities are distinct from concepts: a concept frames an idea or mechanism; an entity is a specific, identifiable thing in the world.",
-      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "entity" },
         "summary": {
-          "$ref": "sctx://_sctx_base#/$defs/summary"
+          "$ref": "sctx://core/_sctx_base#/$defs/summary"
         },
         "sources": {
           "type": "array",
-          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "items": { "$ref": "sctx://core/_sctx_base#/$defs/wikilink" },
           "description": "Wikilinks to source pages that contributed to this entity page"
         },
         "related": {
           "type": "array",
-          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "items": { "$ref": "sctx://core/_sctx_base#/$defs/wikilink" },
           "description": "Wikilinks to related entity, concept, or synthesis pages"
         }
       },
@@ -177,20 +177,20 @@
     "synthesis": {
       "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" }],
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "synthesis" },
         "summary": {
-          "$ref": "sctx://_sctx_base#/$defs/summary"
+          "$ref": "sctx://core/_sctx_base#/$defs/summary"
         },
         "sources": {
           "type": "array",
-          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "items": { "$ref": "sctx://core/_sctx_base#/$defs/wikilink" },
           "description": "Wikilinks to source pages this synthesis draws from"
         },
         "concepts": {
           "type": "array",
-          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "items": { "$ref": "sctx://core/_sctx_base#/$defs/wikilink" },
           "description": "Wikilinks to concept pages this synthesis connects"
         }
       },
@@ -207,8 +207,8 @@
     },
     "note": {
       "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" }],
+      "description": "Personal notes, journal entries, talk notes, or rough thoughts not drawn from an external URL.",
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "note" },
         "date": {
@@ -230,7 +230,7 @@
     "index": {
       "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" }],
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "index" }
       },

package/dist/schemas/_ost_strict.json

@@ -1,6 +1,6 @@
 {
-  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
-  "$id": "sctx://_ost_strict",
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json",
+  "$id": "sctx://core/_ost_strict",
   // Shared definitions for the strict OST (Opportunity Solution Tree) schema.
   // This schema follows Teresa Torres' canonical 4-level structure as described in
   // "Continuous Discovery Habits" (2021) and at producttalk.org.

package/dist/schemas/_sctx_base.json

@@ -1,6 +1,6 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "sctx://_sctx_base",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sctx://core/_sctx_base",
   "description": "Shared definitions for structured-context schemas",
   "$defs": {
     "title": {

package/dist/schemas/_strategy_general.json

@@ -1,9 +1,9 @@
 {
-  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
-  "$id": "sctx://_strategy_general",
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json",
+  "$id": "sctx://core/_strategy_general",
   // Shared entity definitions for strategy-general schemas.
-  // Provides a default hierarchy, aliases, relationships, and entity type $defs.
-  // Composing schemas can override the hierarchy by defining their own.
+  // Provides a hierarchy, aliases, relationships, and entity type $defs.
+  // Schemas that import this partial get its metadata; a $ref to its $defs alone brings none.
   "$metadata": {
     "hierarchy": {
       "levels": [
@@ -45,7 +45,7 @@
   "$defs": {
     "dashboard": {
       "type": "object",
-      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "dashboard" }
       },
@@ -54,7 +54,7 @@
     },
     "ost_on_a_page": {
       "type": "object",
-      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "allOf": [{ "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "enum": ["ost_on_a_page", "space_on_a_page"] }
       },
@@ -64,8 +64,8 @@
     "vision": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "vision" }
@@ -83,9 +83,9 @@
     "mission": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "mission" }
@@ -103,13 +103,13 @@
     "goal": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "enum": ["goal", "outcome"] },
-        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" }
+        "priority": { "$ref": "sctx://core/_sctx_base#/$defs/priority" }
       },
       "required": ["type"],
       "additionalProperties": true,
@@ -125,16 +125,16 @@
     "opportunity": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "opportunity" },
-        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" },
-        "impact": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
-        "feasibility": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
-        "resources": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "priority": { "$ref": "sctx://core/_sctx_base#/$defs/priority" },
+        "impact": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
+        "feasibility": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
+        "resources": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
         "timeline": {
           "type": "string",
           "description": "Timeline estimate (e.g., S-M, M-L)"
@@ -158,16 +158,16 @@
     "solution": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "solution" },
-        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" },
-        "impact": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
-        "feasibility": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
-        "resources": { "$ref": "sctx://_sctx_base#/$defs/assessment" },
+        "priority": { "$ref": "sctx://core/_sctx_base#/$defs/priority" },
+        "impact": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
+        "feasibility": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
+        "resources": { "$ref": "sctx://core/_sctx_base#/$defs/assessment" },
         "timeline": {
           "type": "string",
           "description": "Timeline estimate (e.g., S-M, M-L)"
@@ -191,9 +191,9 @@
     "experiment": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "enum": ["experiment", "assumption_test", "test"] }
@@ -216,9 +216,9 @@
     "assumption": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "assumption" },
@@ -242,9 +242,9 @@
     "problem_statement": {
       "type": "object",
       "allOf": [
-        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
-        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+        { "$ref": "sctx://core/_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://core/_sctx_base#/$defs/ostEntityProps" }
       ],
       "properties": {
         "type": { "const": "problem_statement" }