structured-context 0.9.2 → 0.9.3

package/README.md

@@ -55,12 +55,13 @@ Install globally (recommended):
 
 ```bash
 bun install -g structured-context
+sctx --help
 ```
 
 Or use directly via `bunx`:
 
 ```bash
-bunx structured-context validate <space>
+bunx structured-context --help
 ```
 
 ## Setup for AI Agents
@@ -179,15 +180,18 @@ Bare wikilink items (`- [[Existing Node]]`) in any embedding section populate a
 With `fieldOn: "parent"`, embedded child nodes (parsed from a matching heading's list or table) are appended as wikilinks to the parent's `field` array, rather than receiving a `parent` field. This matches schemas where the content model naturally lists children on the parent (e.g. `activity.tasks: ["[[Task A]]"]`).
 
 Metadata is composable across `$ref` graphs:
-- zero or one metadata provider may define `hierarchy`
+- `hierarchy`: multiple schema files may define a hierarchy; **last one wins** (root schema overrides partials)
 - `aliases` are shallow-merged (later wins)
 - `rules` merge by `id`; conflicts error unless the later rule sets `override: true`
 - `$metadata.rules` supports `$ref` imports for reusable rule packs
+- `relationships` are collected from all files
 
-If no provider defines `hierarchy`, hierarchy-specific checks are skipped. Reading a `space_on_a_page` file still requires `hierarchy.levels`.
+If no file defines `hierarchy`, hierarchy-specific checks are skipped.
 
 **Customizing Schemas:**
-- **Partial schemas**: Files starting with an underscore (like `_sctx_base.json`) are loaded and used to resolve references (using `$ref`).
+- **Partial schemas**: Files starting with an underscore (like `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`) are loaded and used to resolve references (using `$ref`).
+- **Partials as entity libraries**: Partials can define reusable entity types in `$defs` that composing schemas reference via `$ref`. Bundled partials like `_strategy_general` and `_knowledge_wiki` provide common entity sets for strategy and wiki content.
+- **Partials can carry metadata**: Unlike plain JSON Schema, partials may include `$metadata` (hierarchy, aliases, relationships, rules). This makes them self-contained units that bundle both type definitions and behavioral metadata.
 - **No-metadata partials**: If a partial has no `$metadata`, prefer `$schema: "http://json-schema.org/draft-07/schema#"` so it validates standalone as plain JSON Schema.
 - **Loading priority**: Partial schemas are loaded from both the default schema directory and the directory of your specified target schema.
 - **Transitive resolution**: `$ref` chains are resolved recursively across files/schemas (including nested `allOf` usage in partials).

package/dist/schema/schema.js

@@ -255,17 +255,14 @@ function areRulesEquivalent(left, right) {
 }
 function extractMetadata(schema, schemaRefRegistry) {
     const metadataProviders = collectMetadataProviders(schema, schemaRefRegistry);
-    let hierarchyProvider;
     let mergedHierarchy;
     const mergedAliases = {};
     const mergedRules = new Map();
     const mergedRelationships = [];
     for (const provider of metadataProviders) {
         if (provider.metadata.hierarchy) {
-            if (mergedHierarchy) {
-                throw new Error(`Multiple metadata providers define "$metadata.hierarchy": "${hierarchyProvider}" and "${provider.schemaId}". Exactly one provider is allowed.`);
-            }
-            hierarchyProvider = provider.schemaId;
+            // Later providers (including root schema) override earlier ones (e.g. partials).
+            // This allows partials to define a default hierarchy that composing schemas can override.
             mergedHierarchy = provider.metadata.hierarchy;
         }
         if (provider.metadata.aliases) {
@@ -294,6 +291,14 @@ function extractMetadata(schema, schemaRefRegistry) {
             }
         }
     }
+    // Collect valid type names from the schema's oneOf list for validation
+    const validTypeNames = extractSchemaTypeNames(schema, schemaRefRegistry);
+    // Validate and filter metadata references against valid type names
+    validateMetadataReferences({ mergedHierarchy, mergedAliases, mergedRules, mergedRelationships }, validTypeNames);
+    // Filter relationships to only include those where both parent and child types are valid
+    const filteredRelationships = mergedRelationships.filter((rel) => {
+        return validTypeNames.has(rel.parent) && validTypeNames.has(rel.type);
+    });
     const levels = mergedHierarchy?.levels.map((entry) => {
         if (typeof entry === 'string') {
             return { type: entry, field: 'parent', fieldOn: 'child', multiple: false, selfRef: false };
@@ -321,8 +326,8 @@ function extractMetadata(schema, schemaRefRegistry) {
             : undefined,
         typeAliases: Object.keys(mergedAliases).length > 0 ? mergedAliases : undefined,
         rules: mergedRules.size > 0 ? [...mergedRules.values()].map(({ rule }) => normalizeRule(rule)) : undefined,
-        relationships: mergedRelationships.length > 0
-            ? mergedRelationships.map((rel) => ({
+        relationships: filteredRelationships.length > 0
+            ? filteredRelationships.map((rel) => ({
                 ...rel,
                 field: rel.field ?? 'parent',
                 fieldOn: rel.fieldOn === 'parent' ? 'parent' : 'child',
@@ -331,6 +336,38 @@ function extractMetadata(schema, schemaRefRegistry) {
             : undefined,
     };
 }
+function validateMetadataReferences(metadata, validTypes) {
+    // Skip validation if no types are defined (e.g., schemas without oneOf or placeholder schemas)
+    if (validTypes.size === 0) {
+        return;
+    }
+    const errors = [];
+    // Validate hierarchy level types
+    if (metadata.mergedHierarchy?.levels) {
+        for (const level of metadata.mergedHierarchy.levels) {
+            const typeName = typeof level === 'string' ? level : level.type;
+            if (!validTypes.has(typeName)) {
+                errors.push(`Hierarchy level "${typeName}" is not a valid type in the schema's oneOf list`);
+            }
+        }
+    }
+    // Validate alias targets (the values)
+    for (const [alias, target] of Object.entries(metadata.mergedAliases)) {
+        if (!validTypes.has(target)) {
+            errors.push(`Alias "${alias}" → "${target}" references type "${target}" which is not in the schema's oneOf list`);
+        }
+    }
+    // Note: relationships are filtered (not validated) - see extractMetadata
+    // Validate rule types
+    for (const { rule } of metadata.mergedRules.values()) {
+        if (rule.type && !validTypes.has(rule.type)) {
+            errors.push(`Rule "${rule.id}" has type "${rule.type}" which is not in the schema's oneOf list`);
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`Schema metadata validation failed:\n  - ${errors.join('\n  - ')}`);
+    }
+}
 export function extractEntityInfo(schema, schemaRefRegistry) {
     if (!Array.isArray(schema.oneOf))
         return [];

package/dist/schemas/_knowledge_wiki.json

@@ -0,0 +1,246 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "$id": "sctx://_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.
+  "$metadata": {
+    "aliases": {
+      "source_summary": "source",
+      "study": "source",
+      "article": "source",
+      "paper": "source",
+      "research": "source",
+      "comparison": "synthesis",
+      "query": "synthesis"
+    },
+    "relationships": [
+      {
+        "parent": "source",
+        "type": "source",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "source",
+        "type": "synthesis",
+        "field": "sources",
+        "fieldOn": "child",
+        "multiple": true
+      },
+      {
+        "parent": "source",
+        "type": "entity",
+        "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"
+      }
+    ]
+  },
+  "$defs": {
+    "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" }],
+      "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"]
+        }
+      ]
+    },
+    "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" }],
+      "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"]
+        }
+      ]
+    },
+    "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" }],
+      "properties": {
+        "type": { "const": "entity" },
+        "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 entity page"
+        },
+        "related": {
+          "type": "array",
+          "items": { "$ref": "sctx://_sctx_base#/$defs/wikilink" },
+          "description": "Wikilinks to related entity, concept, or synthesis pages"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "entity",
+          "summary": "AI safety research lab founded by Dario Amodei and Daniela Amodei",
+          "tags": ["company", "ai", "safety"]
+        }
+      ]
+    },
+    "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" }],
+      "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]]"]
+        }
+      ]
+    },
+    "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" }],
+      "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"]
+        }
+      ]
+    },
+    "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" }],
+      "properties": {
+        "type": { "const": "index" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "index"
+        }
+      ]
+    }
+  }
+}

package/dist/schemas/_strategy_general.json

@@ -0,0 +1,262 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
+  "$id": "sctx://_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.
+  "$metadata": {
+    "hierarchy": {
+      "levels": [
+        "vision",
+        "mission",
+        { "type": "goal", "selfRef": true, "matchers": ["Goals"] },
+        { "type": "opportunity", "selfRef": true, "matchers": ["Opportunities"] },
+        {
+          "type": "solution",
+          "selfRef": true,
+          "matchers": ["Solutions", "Potential solutions", "Solutions considered", "Possible solutions"]
+        },
+        "experiment"
+      ]
+    },
+    "aliases": {
+      "outcome": "goal",
+      "assumption_test": "experiment",
+      "test": "experiment"
+    },
+    "relationships": [
+      {
+        "parent": "opportunity",
+        "type": "problem_statement",
+        "templateFormat": "heading",
+        "matchers": ["Problem statement", "What problem are we solving?"],
+        "multiple": false
+      },
+      {
+        "parent": "opportunity",
+        "type": "assumption",
+        "templateFormat": "table",
+        "matchers": ["Assumptions", "^Assumptions?$"],
+        "embeddedTemplateFields": ["assumption", "status", "confidence"],
+        "multiple": true
+      }
+    ]
+  },
+  "$defs": {
+    "dashboard": {
+      "type": "object",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "const": "dashboard" }
+      },
+      "required": ["type"],
+      "additionalProperties": true
+    },
+    "ost_on_a_page": {
+      "type": "object",
+      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
+      "properties": {
+        "type": { "enum": ["ost_on_a_page", "space_on_a_page"] }
+      },
+      "required": ["type"],
+      "additionalProperties": true
+    },
+    "vision": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "vision" }
+      },
+      "required": ["type"],
+      "not": { "required": ["parent"] },
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "vision",
+          "status": "active"
+        }
+      ]
+    },
+    "mission": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "mission" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "mission",
+          "status": "active",
+          "parent": "[[Personal Vision]]"
+        }
+      ]
+    },
+    "goal": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "enum": ["goal", "outcome"] },
+        "priority": { "$ref": "sctx://_sctx_base#/$defs/priority" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "goal",
+          "status": "active",
+          "parent": "[[My Mission (2026)]]",
+          "priority": "p2"
+        }
+      ]
+    },
+    "opportunity": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_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" },
+        "timeline": {
+          "type": "string",
+          "description": "Timeline estimate (e.g., S-M, M-L)"
+        },
+        "next_steps": {
+          "type": "string",
+          "description": "Next steps for this opportunity"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "opportunity",
+          "status": "identified",
+          "parent": "[[Career Growth]]",
+          "priority": "p2"
+        }
+      ]
+    },
+    "solution": {
+      "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" },
+        "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" },
+        "timeline": {
+          "type": "string",
+          "description": "Timeline estimate (e.g., S-M, M-L)"
+        },
+        "next_steps": {
+          "type": "string",
+          "description": "Next steps for this solution"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "solution",
+          "status": "identified",
+          "parent": "[[Some Opportunity]]",
+          "priority": "p3"
+        }
+      ]
+    },
+    "experiment": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "enum": ["experiment", "assumption_test", "test"] }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "experiment",
+          "status": "exploring",
+          "parent": "[[Build a Side Project]]"
+        },
+        {
+          "type": "test",
+          "status": "active",
+          "parent": "[[Mobile App Solution]]"
+        }
+      ]
+    },
+    "assumption": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "assumption" },
+        "confidence": {
+          "type": "string",
+          "enum": ["low", "medium", "high"],
+          "description": "Confidence level in this assumption"
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "assumption",
+          "status": "identified",
+          "parent": "[[Some Opportunity]]",
+          "confidence": "medium"
+        }
+      ]
+    },
+    "problem_statement": {
+      "type": "object",
+      "allOf": [
+        { "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/parentNodeProps" },
+        { "$ref": "sctx://_sctx_base#/$defs/ostEntityProps" }
+      ],
+      "properties": {
+        "type": { "const": "problem_statement" }
+      },
+      "required": ["type"],
+      "additionalProperties": true,
+      "examples": [
+        {
+          "type": "problem_statement",
+          "status": "identified"
+        }
+      ]
+    }
+  }
+}