structured-context 0.9.2 → 0.10.0

package/dist/schemas/knowledge_wiki.json

@@ -3,243 +3,13 @@
   "$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",
-      "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"
-      }
-    ]
-  },
+  "allOf": [{ "$ref": "sctx://_knowledge_wiki" }],
   "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 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"]
-        }
-      ]
-    },
-    {
-      "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"
-        }
-      ]
-    }
+    { "$ref": "sctx://_knowledge_wiki#/$defs/source" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/concept" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/entity" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/synthesis" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/note" },
+    { "$ref": "sctx://_knowledge_wiki#/$defs/index" }
   ]
 }

package/dist/schemas/strategy_general.json

@@ -2,260 +2,18 @@
   "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
   "$id": "sctx://strategy_general",
   "title": "Strategy and opportunity ladder",
-  "description": "Validates frontmatter for space node files",
-  "$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
-      }
-    ]
-  },
+  "description": "Validates frontmatter for space node files. Composes strategy_general entities from the bundled partial. Override the hierarchy in $metadata to customize the level structure.",
+  "allOf": [{ "$ref": "sctx://_strategy_general" }],
   "oneOf": [
-    {
-      "type": "object",
-      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
-      "properties": {
-        "type": { "const": "dashboard" }
-      },
-      "required": ["type"],
-      "additionalProperties": true
-    },
-    {
-      "type": "object",
-      "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
-      "properties": {
-        "type": { "enum": ["ost_on_a_page", "space_on_a_page"] }
-      },
-      "required": ["type"],
-      "additionalProperties": true
-    },
-    {
-      "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"
-        }
-      ]
-    },
-    {
-      "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]]"
-        }
-      ]
-    },
-    {
-      "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"
-        }
-      ]
-    },
-    {
-      "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"
-        }
-      ]
-    },
-    {
-      "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"
-        }
-      ]
-    },
-    {
-      "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]]"
-        }
-      ]
-    },
-    {
-      "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"
-        }
-      ]
-    },
-    {
-      "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"
-        }
-      ]
-    }
+    { "$ref": "sctx://_strategy_general#/$defs/dashboard" },
+    { "$ref": "sctx://_strategy_general#/$defs/ost_on_a_page" },
+    { "$ref": "sctx://_strategy_general#/$defs/vision" },
+    { "$ref": "sctx://_strategy_general#/$defs/mission" },
+    { "$ref": "sctx://_strategy_general#/$defs/goal" },
+    { "$ref": "sctx://_strategy_general#/$defs/opportunity" },
+    { "$ref": "sctx://_strategy_general#/$defs/solution" },
+    { "$ref": "sctx://_strategy_general#/$defs/experiment" },
+    { "$ref": "sctx://_strategy_general#/$defs/assumption" },
+    { "$ref": "sctx://_strategy_general#/$defs/problem_statement" }
   ]
 }

package/dist/types.d.ts

@@ -91,10 +91,10 @@ export type ParseIssue = {
     file: string;
     /** error: prevented the file from producing nodes; warning: file was silently excluded. */
     severity: 'error' | 'warning';
-    /** empty: no content; no-type: no type field;
+    /** no-type: no type field;
      *  parse: parse failure (syntax issue or unexpected content);
      *  plugins may choose to provide additional types. */
-    type: 'empty' | 'no-type' | 'parse' | string;
+    type: 'no-type' | 'parse' | string;
     /** Human-readable detail. */
     message?: string;
 };
@@ -155,3 +155,21 @@ export type SpaceContext = {
     /** Directory of the config file that defines this space. Used for resolving relative paths in plugin configs. */
     configDir: string;
 };
+export interface FileValidationResult {
+    file: string;
+    label: string;
+    space: string;
+    /** Errors keyed by composite id (e.g. `schema:/status:enum:active`, `rule:my-rule-id`). */
+    errors: Record<string, {
+        kind: string;
+        message: string;
+    }>;
+    errorCount: number;
+    inSpace: true;
+}
+export interface FileNotInSpaceResult {
+    file: string;
+    inSpace: false;
+    message: string;
+}
+export type ValidateFileOutput = FileValidationResult | FileNotInSpaceResult;

package/dist/validate.d.ts

@@ -0,0 +1,50 @@
+import type { ErrorObject } from 'ajv';
+import type { Config } from './config';
+import { extractEntityInfo } from './schema/schema';
+import type { GraphViolation, ParseIssue, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
+export interface FormattedError {
+    message: string;
+    dedupeKey: string;
+}
+export interface ValidationResult {
+    validCount: number;
+    nodeErrorCount: number;
+    nodeErrors: Array<{
+        file: string;
+        errors: ErrorObject[];
+        nodeData: Record<string, unknown>;
+    }>;
+    refErrors: Array<{
+        file: string;
+        parent: string;
+        error: string;
+    }>;
+    duplicateErrors: Array<{
+        title: string;
+        files: string[];
+    }>;
+    ruleViolations: RuleViolation[];
+    hierarchyViolations: GraphViolation[];
+    orphans: SpaceNode[];
+    parseIssues: ParseIssue[];
+}
+/**
+ * Format AJV errors for better readability.
+ * Groups related errors and extracts helpful context like allowed values.
+ */
+export declare function formatErrors(errors: ErrorObject[], schema: SchemaWithMetadata, schemaRefRegistry: Parameters<typeof extractEntityInfo>[1], nodeData: Record<string, unknown>): FormattedError[];
+/**
+ * Run full validation on a space and return a structured result.
+ * Does not output to console or call process.exit.
+ */
+export declare function validateSpace(context: SpaceContext): Promise<ValidationResult>;
+/**
+ * Validate a single file within its space.
+ *
+ * Reads the full space (required for graph correctness) but filters all reported
+ * errors to only those attributable to the target file.
+ *
+ * Returns a result object — does not output to console or call process.exit.
+ * If the file is not in any configured space, returns a result with `inSpace: false`.
+ */
+export declare function validateFile(filePath: string, config: Config): Promise<ValidateFileOutput>;