@aikdna/kdna-core 0.1.0

package/schema/kdna-file.schema.json

@@ -0,0 +1,262 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aikdna.com/schema/kdna-file.schema.json",
+  "title": "KDNA Single-File Format",
+  "description": "Schema for the .kdna single-file distribution format. Combines all KDNA domain files into one transportable file.",
+  "type": "object",
+  "required": ["kdna_spec", "meta", "core", "patterns"],
+  "properties": {
+    "kdna_spec": {
+      "type": "string",
+      "description": "KDNA spec version this file conforms to (e.g., '0.4')."
+    },
+    "meta": {
+      "type": "object",
+      "description": "Domain metadata — equivalent to kdna.json fields.",
+      "required": ["name", "domain", "version"],
+      "properties": {
+        "name": { "type": "string", "description": "Human-readable domain name." },
+        "domain": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Domain identifier (snake_case)." },
+        "version": { "type": "string", "description": "Semantic version (MAJOR.MINOR.PATCH)." },
+        "spec_version": { "type": "string", "description": "KDNA spec version this domain conforms to." },
+        "created": { "type": "string", "description": "ISO date of first creation." },
+        "updated": { "type": "string", "description": "ISO date of last update." },
+        "purpose": { "type": "string", "description": "What judgment this domain improves." },
+        "description": { "type": "string" },
+        "language": { "type": "string" },
+        "languages": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "author": {
+      "type": "object",
+      "description": "Domain author information.",
+      "properties": {
+        "name": { "type": "string" },
+        "id": { "type": "string" },
+        "email": { "type": "string", "format": "email" }
+      }
+    },
+    "license": {
+      "type": "object",
+      "description": "License information.",
+      "properties": {
+        "type": { "type": "string" },
+        "url": { "type": "string", "format": "uri" }
+      }
+    },
+    "status": {
+      "type": "string",
+      "enum": ["experimental", "basic", "stable", "pro"],
+      "description": "Domain maturity level."
+    },
+    "access": {
+      "type": "string",
+      "enum": ["open", "licensed", "runtime"],
+      "description": "Access mode for this domain."
+    },
+    "keywords": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Discovery keywords."
+    },
+    "core": {
+      "type": "object",
+      "description": "Core cognition — equivalent to KDNA_Core.json.",
+      "required": ["axioms", "ontology", "frameworks", "core_structure", "stances"],
+      "properties": {
+        "axioms": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["id", "one_sentence", "full_statement", "why"],
+            "properties": {
+              "id": { "type": "string", "description": "Unique identifier (e.g., 'AX-001')." },
+              "one_sentence": { "type": "string", "minLength": 10, "description": "One-sentence judgment principle." },
+              "full_statement": { "type": "string", "minLength": 20, "description": "Full explanation — testable and domain-specific." },
+              "why": { "type": "string", "minLength": 10, "description": "Why this axiom matters for agent judgment." }
+            }
+          }
+        },
+        "ontology": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["id", "one_sentence", "essence", "boundary", "trigger_signal"],
+            "properties": {
+              "id": { "type": "string" },
+              "one_sentence": { "type": "string" },
+              "essence": { "type": "string", "minLength": 10, "description": "Operational meaning — what the agent needs to check." },
+              "boundary": { "type": "string", "minLength": 5, "description": "What this concept is NOT. Must name a specific concept, not just 'not X'." },
+              "trigger_signal": { "type": "string", "minLength": 5, "description": "Observable words or patterns that signal this concept is relevant." }
+            }
+          }
+        },
+        "frameworks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "name", "when_to_use", "steps"],
+            "properties": {
+              "id": { "type": "string" },
+              "name": { "type": "string" },
+              "when_to_use": { "type": "string" },
+              "steps": { "type": "array", "minItems": 1, "items": { "type": "string" } }
+            }
+          }
+        },
+        "core_structure": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["from", "to", "via"],
+            "properties": {
+              "from": { "type": "string" },
+              "to": { "type": "string" },
+              "via": { "type": "string" }
+            }
+          }
+        },
+        "stances": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "anyOf": [
+              { "type": "string" },
+              { "type": "object", "required": ["stance"] }
+            ]
+          }
+        }
+      }
+    },
+    "patterns": {
+      "type": "object",
+      "description": "Patterns — equivalent to KDNA_Patterns.json.",
+      "required": ["terminology", "misunderstandings", "self_check"],
+      "properties": {
+        "terminology": {
+          "type": "object",
+          "minProperties": 1,
+          "properties": {
+            "standard_terms": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["term", "definition"],
+                "properties": {
+                  "term": { "type": "string" },
+                  "definition": { "type": "string" }
+                }
+              }
+            },
+            "preferred_terms": {
+              "type": "array",
+              "items": { "type": "object" }
+            },
+            "banned_terms": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["term", "why", "replace_with"],
+                "properties": {
+                  "term": { "type": "string" },
+                  "why": { "type": "string" },
+                  "replace_with": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "misunderstandings": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["id", "wrong", "correct", "key_distinction", "why"],
+            "properties": {
+              "id": { "type": "string" },
+              "wrong": { "type": "string", "minLength": 10 },
+              "correct": { "type": "string", "minLength": 10 },
+              "key_distinction": { "type": "string", "minLength": 10 },
+              "why": { "type": "string", "minLength": 10 }
+            }
+          }
+        },
+        "self_check": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "anyOf": [
+              { "type": "string" },
+              { "type": "object", "required": ["question"] }
+            ]
+          }
+        }
+      }
+    },
+    "scenarios": {
+      "type": "object",
+      "description": "Optional scenarios (KDNA_Scenarios.json).",
+      "properties": {
+        "scenes": {
+          "type": "array",
+          "items": { "type": "object" }
+        }
+      }
+    },
+    "cases": {
+      "type": "object",
+      "description": "Optional cases (KDNA_Cases.json).",
+      "properties": {
+        "cases": {
+          "type": "array",
+          "items": { "type": "object" }
+        }
+      }
+    },
+    "reasoning": {
+      "type": "object",
+      "description": "Optional reasoning chains (KDNA_Reasoning.json).",
+      "properties": {
+        "reasoning_chains": {
+          "type": "array",
+          "items": { "type": "object" }
+        }
+      }
+    },
+    "evolution": {
+      "type": "object",
+      "description": "Optional evolution stages (KDNA_Evolution.json).",
+      "properties": {
+        "stages": {
+          "type": "array",
+          "items": { "type": "object" }
+        }
+      }
+    },
+    "registry": {
+      "type": "object",
+      "description": "Optional registry metadata.",
+      "properties": {
+        "repo": { "type": "string" },
+        "eval_score": { "type": "number" },
+        "quality_badge": { "type": "string" }
+      }
+    },
+    "evaluation_history": {
+      "type": "array",
+      "description": "Benchmark evaluation history.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "version": { "type": "string" },
+          "eval_score": { "type": "number" },
+          "evaluated_at": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * @aikdna/kdna-core — CJS entry point
+ */
+const loader = require('./loader');
+const lint = require('./lint-pure');
+const validate = require('./validate-pure');
+const render = require('./render');
+
+module.exports = {
+  ...loader,
+  ...lint,
+  ...validate,
+  ...render,
+};

package/src/index.mjs

@@ -0,0 +1,17 @@
+/**
+ * @aikdna/kdna-core — ESM entry point
+ */
+export {
+  FILE_MAP,
+  loadCorePatternsFromData,
+  loadDomainFromData,
+  loadDomainFromFiles,
+  classifyInput,
+  formatContext,
+} from './loader.js';
+
+export { lintDomain } from './lint-pure.js';
+
+export { validateDomainSchema, validateCrossFile } from './validate-pure.js';
+
+export { renderPreviewHTML, escHtml, renderCard } from './render.js';

package/src/lint-pure.js

@@ -0,0 +1,197 @@
+/**
+ * KDNA Lint — Pure structural and content validation.
+ *
+ * Operates on in-memory data maps. No fs, no path, no Node.js dependencies.
+ * Input: { 'KDNA_Core.json': parsedObj, 'KDNA_Patterns.json': parsedObj, ... }
+ * Output: { errors: string[], warnings: string[] }
+ */
+
+/**
+ * Lint a KDNA domain from a map of parsed JSON objects.
+ *
+ * @param {Object} dataMap — keyed by filename, e.g. { 'KDNA_Core.json': {...}, ... }
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function lintDomain(dataMap) {
+  const errors = [];
+  const warnings = [];
+
+  function has(o, k) {
+    return Object.prototype.hasOwnProperty.call(o || {}, k);
+  }
+
+  function req(o, k, loc, hint) {
+    if (!has(o, k) || o[k] === '' || o[k] == null) {
+      let msg = `${loc}: missing required field "${k}"`;
+      if (hint) msg += `\n    → ${hint}`;
+      errors.push(msg);
+    }
+  }
+
+  function meta(o, file) {
+    req(o, 'meta', file);
+    if (!o.meta) return;
+    ['version', 'domain', 'created', 'purpose', 'load_condition'].forEach((f) =>
+      req(o.meta, f, `${file}.meta`),
+    );
+  }
+
+  function ids(v, file, set) {
+    if (Array.isArray(v)) return v.forEach((x) => ids(x, file, set));
+    if (v && typeof v === 'object') {
+      if (typeof v.id === 'string') {
+        if (set.has(v.id)) errors.push(`${file}: duplicate id "${v.id}"`);
+        set.add(v.id);
+      }
+      Object.values(v).forEach((x) => ids(x, file, set));
+    }
+  }
+
+  function yesno(s, loc) {
+    const t = String(s || '')
+      .trim()
+      .toLowerCase();
+    const cn = String(s || '').trim();
+    if (
+      t.endsWith('?') ||
+      cn.endsWith('？') ||
+      cn.endsWith('吗') ||
+      cn.includes('是否') ||
+      /^(have|has|can|does|do|is|are|能不能|会不会|有没有|要不要|是不是)/.test(t)
+    )
+      return;
+    warnings.push(
+      `${loc}: self_check should be answerable with yes/no\n    → Try: "Did the response [do X specific domain check]?"`,
+    );
+  }
+
+  // Check required files
+  const requiredFiles = ['KDNA_Core.json', 'KDNA_Patterns.json'];
+  for (const f of requiredFiles) {
+    if (!dataMap[f]) errors.push(`Missing required file: ${f}`);
+  }
+
+  // Check file count
+  const kdnaFiles = Object.keys(dataMap).filter(
+    (f) => f.endsWith('.json') && f !== 'kdna.json',
+  );
+  if (kdnaFiles.length > 6) errors.push(`Domain has ${kdnaFiles.length} JSON files; KDNA allows at most 6.`);
+
+  // Validate meta on all files
+  for (const f of kdnaFiles) {
+    if (dataMap[f]) meta(dataMap[f], f);
+  }
+
+  // Check duplicate IDs
+  const seen = new Set();
+  for (const f of kdnaFiles) {
+    if (dataMap[f]) ids(dataMap[f], f, seen);
+  }
+
+  // Validate KDNA_Core.json
+  const core = dataMap['KDNA_Core.json'];
+  if (core) {
+    ['axioms', 'ontology', 'frameworks', 'core_structure', 'stances'].forEach((f) =>
+      req(core, f, 'KDNA_Core.json'),
+    );
+    (core.axioms || []).forEach((a, i) =>
+      [
+        ['id', 'Unique identifier like "AX-001". See SPEC.md §5.2'],
+        [
+          'one_sentence',
+          'One-sentence judgment principle. Must be specific enough to change agent behavior. See docs/authoring-guide.md',
+        ],
+        [
+          'full_statement',
+          'Full explanation of the axiom — testable and domain-specific. See SPEC.md §5.2',
+        ],
+        ['why', 'What the agent would get wrong WITHOUT this axiom. See SPEC.md §5.2'],
+      ].forEach(([f, hint]) => req(a, f, `KDNA_Core.json.axioms[${i}]`, hint)),
+    );
+    (core.ontology || []).forEach((c, i) =>
+      [
+        ['id', 'Unique identifier like "CON-001". See SPEC.md §5.3'],
+        ['one_sentence', 'Name one central concept the agent must distinguish.'],
+        [
+          'essence',
+          'Operational meaning in this domain — not a dictionary definition. See docs/authoring-guide.md',
+        ],
+        [
+          'boundary',
+          'What this concept is NOT. Name a specific concept it is often confused with. See docs/authoring-guide.md',
+        ],
+        [
+          'trigger_signal',
+          'Observable words or patterns that signal this concept is relevant. See SPEC.md §5.3',
+        ],
+      ].forEach(([f, hint]) => req(c, f, `KDNA_Core.json.ontology[${i}]`, hint)),
+    );
+    (core.frameworks || []).forEach((fw, i) =>
+      [
+        ['id', 'Unique identifier like "FW-001". See SPEC.md §5.4'],
+        ['name', 'Descriptive name for this framework.'],
+        ['when_to_use', 'Specific condition or context where this framework applies.'],
+        [
+          'steps',
+          'Array of actionable steps. Each step should tell the agent what to do. See SPEC.md §5.4',
+        ],
+      ].forEach(([f, hint]) => req(fw, f, `KDNA_Core.json.frameworks[${i}]`, hint)),
+    );
+  }
+
+  // Validate KDNA_Patterns.json
+  const pat = dataMap['KDNA_Patterns.json'];
+  if (pat) {
+    ['terminology', 'misunderstandings', 'self_check'].forEach((f) =>
+      req(pat, f, 'KDNA_Patterns.json'),
+    );
+    ((pat.terminology || {}).banned_terms || []).forEach((b, i) =>
+      ['term', 'why', 'replace_with'].forEach((f) =>
+        req(b, f, `KDNA_Patterns.json.terminology.banned_terms[${i}]`),
+      ),
+    );
+    (pat.misunderstandings || []).forEach((m, i) =>
+      [
+        ['id', 'Unique identifier like "MS-001". See SPEC.md §6.3'],
+        [
+          'wrong',
+          'Common wrong interpretation an agent without domain cognition would make. See docs/authoring-guide.md',
+        ],
+        ['correct', 'Correct interpretation according to domain principles. See SPEC.md §6.3'],
+        [
+          'key_distinction',
+          'The specific conceptual boundary the agent must preserve. See SPEC.md §6.3',
+        ],
+        ['why', 'What bad judgment results from the wrong interpretation. See SPEC.md §6.3'],
+      ].forEach(([f, hint]) => req(m, f, `KDNA_Patterns.json.misunderstandings[${i}]`, hint)),
+    );
+    (pat.self_check || []).forEach((s, i) => yesno(s, `KDNA_Patterns.json.self_check[${i}]`));
+  }
+
+  // Validate KDNA_Reasoning.json
+  const rea = dataMap['KDNA_Reasoning.json'];
+  if (rea) {
+    (rea.reasoning_chains || []).forEach((r, i) =>
+      ['id', 'one_sentence', 'logic', 'so_what'].forEach((f) =>
+        req(r, f, `KDNA_Reasoning.json.reasoning_chains[${i}]`),
+      ),
+    );
+  }
+
+  // Cross-reference: scene_id in cases
+  const scen = dataMap['KDNA_Scenarios.json'];
+  const sceneIds = new Set();
+  if (scen) (scen.scenes || []).forEach((s) => sceneIds.add(s.id));
+  const cases = dataMap['KDNA_Cases.json'];
+  if (cases && scen)
+    (cases.cases || []).forEach((c, i) => {
+      if (c.scene_id && !sceneIds.has(c.scene_id))
+        errors.push(
+          `KDNA_Cases.json.cases[${i}]: scene_id "${c.scene_id}" not found in KDNA_Scenarios.json`,
+        );
+    });
+
+  return { errors, warnings };
+}
+
+module.exports = { lintDomain };