@aikdna/kdna-core 0.2.2 → 0.3.0

package/src/compose.js

@@ -120,4 +120,258 @@ function loadAndCompose(dataMaps, options = {}) {
   return { domains, context, activeIndices };
 }
 
-module.exports = { composeContext, classifySignals, composeChecks, loadAndCompose };
+/**
+ * Compose context with source attribution — every axiom, misunderstanding,
+ * banned term, and self-check is prefixed with its origin domain.
+ *
+ * @param {Array<{id:string, core:object, patterns:object}>} domains
+ * @param {object} [options]
+ * @param {string} [options.separator] — section separator
+ * @returns {{context: string, attributionMap: object}}
+ */
+function composeContextWithAttribution(domains, options = {}) {
+  if (!domains || !domains.length) return { context: '', attributionMap: {} };
+
+  const separator = options.separator || '\n\n---\n\n';
+  const lines = [];
+  const attributionMap = {};
+  let axiomIndex = 0;
+  let misreadingIndex = 0;
+  let termIndex = 0;
+  let checkIndex = 0;
+
+  for (const domain of domains) {
+    if (!domain || !domain.core) continue;
+    const name = domain.id || domain.core.meta?.domain || 'unknown';
+    const core = domain.core;
+    const patterns = domain.patterns || {};
+
+    lines.push(`## [${name}] Domain cognition`);
+
+    if (core.axioms?.length) {
+      lines.push(`### Axioms`);
+      for (const a of core.axioms) {
+        const tag = `[${name}:axiom.${a.id}]`;
+        lines.push(`- ${tag} ${a.one_sentence}`);
+        if (a.applies_when?.length) {
+          lines.push(`  APPLIES WHEN: ${a.applies_when.join('; ')}`);
+        }
+        if (a.does_not_apply_when?.length) {
+          lines.push(`  DOES NOT APPLY WHEN: ${a.does_not_apply_when.join('; ')}`);
+        }
+        if (a.failure_risk) lines.push(`  RISK IF MISAPPLIED: ${a.failure_risk}`);
+        attributionMap[tag] = { domain: name, type: 'axiom', id: a.id, index: axiomIndex++ };
+      }
+    }
+
+    if (patterns.misunderstandings?.length) {
+      lines.push(`### Misunderstandings`);
+      for (const m of patterns.misunderstandings) {
+        const tag = `[${name}:misunderstanding.${m.id}]`;
+        lines.push(`- ${tag} WRONG: ${m.wrong}`);
+        lines.push(`  CORRECT: ${m.correct}`);
+        if (m.failure_risk) lines.push(`  RISK: ${m.failure_risk}`);
+        attributionMap[tag] = { domain: name, type: 'misunderstanding', id: m.id, index: misreadingIndex++ };
+      }
+    }
+
+    if (patterns.terminology?.banned_terms?.length) {
+      lines.push(`### Banned terms`);
+      for (const t of patterns.terminology.banned_terms) {
+        const term = typeof t === 'string' ? t : t.term;
+        const tag = `[${name}:banned_term.${term}]`;
+        const replace = typeof t === 'object' ? t.replace_with : null;
+        lines.push(`- ${tag} "${term}"${replace ? ` → use: ${replace}` : ''}`);
+        attributionMap[tag] = { domain: name, type: 'banned_term', term, index: termIndex++ };
+      }
+    }
+
+    if (patterns.self_check?.length) {
+      lines.push(`### Self-checks`);
+      for (const q of patterns.self_check) {
+        const text = typeof q === 'string' ? q : q.question;
+        const tag = `[${name}:self_check.${checkIndex}]`;
+        if (text) lines.push(`- ${tag} ${text}`);
+        attributionMap[tag] = { domain: name, type: 'self_check', index: checkIndex++ };
+      }
+    }
+
+    lines.push(separator.trimEnd());
+  }
+
+  return { context: lines.join('\n'), attributionMap };
+}
+
+/**
+ * Classify signals across a cluster of domains. Returns which domains
+ * matched and which were excluded. Unlike classifySignals (which just
+ * returns indices), this provides full diagnostic info.
+ *
+ * @param {string} input
+ * @param {Array<{id:string, name:string, role:string, core:object}>} domainEntries
+ * @returns {{selected: Array, excluded: Array}}
+ */
+function classifySignalsAcrossDomains(input, domainEntries) {
+  if (!input || !domainEntries?.length) return { selected: [], excluded: [] };
+
+  const lower = input.toLowerCase();
+  const selected = [];
+  const excluded = [];
+
+  for (const entry of domainEntries) {
+    const signals = entry.core?.trigger_signals || [];
+    const negativeSignals = entry.core?.negative_signals || [];
+    const doesNotApply = [];
+    for (const a of entry.core?.axioms || []) {
+      if (Array.isArray(a.does_not_apply_when)) doesNotApply.push(...a.does_not_apply_when);
+    }
+
+    // Check negative signals
+    const blocked = negativeSignals.some((s) => lower.includes(s.toLowerCase())) ||
+      doesNotApply.some((s) => lower.includes(s.toLowerCase()));
+
+    if (blocked) {
+      excluded.push({ id: entry.id, name: entry.name, reason: 'blocked by does_not_apply_when', role: entry.role });
+      continue;
+    }
+
+    // No signals defined → required domain (always active)
+    if (!signals.length) {
+      selected.push({ id: entry.id, name: entry.name, role: entry.role, reason: 'required' });
+      continue;
+    }
+
+    // Check positive signals
+    const matched = signals.some((s) => lower.includes(s.toLowerCase()));
+    if (matched) {
+      selected.push({ id: entry.id, name: entry.name, role: entry.role, reason: 'signal_match' });
+    } else {
+      excluded.push({ id: entry.id, name: entry.name, reason: 'no signal match', role: entry.role });
+    }
+  }
+
+  return { selected, excluded };
+}
+
+/**
+ * Load a cluster from its manifest.
+ *
+ * @param {string} clusterManifestPath — path to kdna.cluster.json
+ * @param {function} domainLoader — fn(domainId) → {core, patterns} or null
+ * @returns {{manifest:object, domains:Array, errors:Array}}
+ */
+function loadCluster(clusterManifestPath, domainLoader) {
+  const fs = require('fs');
+  const manifest = JSON.parse(fs.readFileSync(clusterManifestPath, 'utf8'));
+  const domains = [];
+  const errors = [];
+
+  if (!manifest.domains || !Array.isArray(manifest.domains)) {
+    return { manifest, domains, errors: ['No domains defined in cluster manifest'] };
+  }
+
+  for (const entry of manifest.domains) {
+    try {
+      const loaded = domainLoader(entry.id);
+      if (loaded) {
+        domains.push({ id: entry.id, name: loaded.core?.meta?.domain || entry.id, role: entry.role || 'advisor', required: entry.required !== false, core: loaded.core, patterns: loaded.patterns });
+      } else {
+        errors.push(`Domain ${entry.id}: not found or failed to load`);
+      }
+    } catch (e) {
+      errors.push(`Domain ${entry.id}: ${e.message}`);
+    }
+  }
+
+  return { manifest, domains, errors };
+}
+
+/**
+ * Detect conflicts between loaded domains in a cluster.
+ *
+ * @param {Array<{id:string, core:object, patterns:object}>} domains
+ * @returns {Array<{type:string, domains:string[], description:string}>}
+ */
+function detectDomainConflicts(domains) {
+  if (!domains || domains.length < 2) return [];
+
+  const conflicts = [];
+  const bannedTermMap = new Map();
+
+  // Check banned term conflicts — same term banned by one, preferred by another
+  for (const d of domains) {
+    const terms = d.patterns?.terminology?.banned_terms || [];
+    for (const t of terms) {
+      const term = typeof t === 'string' ? t : t.term;
+      if (bannedTermMap.has(term)) {
+        conflicts.push({
+          type: 'term_conflict',
+          domains: [bannedTermMap.get(term), d.id],
+          description: `Banned term "${term}" appears in multiple domains`,
+        });
+      }
+      bannedTermMap.set(term, d.id);
+    }
+  }
+
+  // Check stance conflicts — contradictory stances
+  for (let i = 0; i < domains.length; i++) {
+    for (let j = i + 1; j < domains.length; j++) {
+      const sA = (domains[i].core?.stances || []).map((s) => (typeof s === 'string' ? s : s.stance));
+      const sB = (domains[j].core?.stances || []).map((s) => (typeof s === 'string' ? s : s.stance));
+      for (const sa of sA) {
+        for (const sb of sB) {
+          // Simple negation check — can be extended
+          if (sa && sb && (sa.includes('not') && sb.toLowerCase().includes(sa.toLowerCase().replace('not ', ''))) ||
+              (sb.includes('not') && sa.toLowerCase().includes(sb.toLowerCase().replace('not ', '')))) {
+            conflicts.push({
+              type: 'stance_conflict',
+              domains: [domains[i].id, domains[j].id],
+              description: `Potential stance conflict: "${sa.slice(0, 60)}" vs "${sb.slice(0, 60)}"`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Generate a judgment trace for a cluster operation.
+ *
+ * @param {object} params
+ * @param {string} params.input — the original user input
+ * @param {Array} params.loadedDomains — all domains in the cluster
+ * @param {Array} params.activeDomains — domains that were activated
+ * @param {Array} params.conflicts — detected conflicts
+ * @returns {object}
+ */
+function generateClusterTrace({ input, loadedDomains, activeDomains, conflicts }) {
+  return {
+    input: (input || '').slice(0, 200),
+    timestamp: new Date().toISOString(),
+    loaded_domains: (loadedDomains || []).map((d) => d.id || d.name || '?'),
+    active_domains: (activeDomains || []).map((d) => d.id || d.name || '?'),
+    active_count: (activeDomains || []).length,
+    domains_excluded: (loadedDomains || []).length - (activeDomains || []).length,
+    conflicts: (conflicts || []).map((c) => ({
+      type: c.type,
+      domains: c.domains,
+      description: c.description,
+    })),
+  };
+}
+
+module.exports = {
+  composeContext,
+  composeContextWithAttribution,
+  classifySignals,
+  classifySignalsAcrossDomains,
+  composeChecks,
+  loadAndCompose,
+  loadCluster,
+  detectDomainConflicts,
+  generateClusterTrace,
+};

package/src/index.mjs

@@ -16,4 +16,4 @@ export { validateDomainSchema, validateCrossFile } from './validate-pure.js';
 
 export { renderPreviewHTML, escHtml, renderCard } from './render.js';
 
-export { composeContext, classifySignals, composeChecks, loadAndCompose } from './compose.js';
+export { composeContext, composeContextWithAttribution, classifySignals, classifySignalsAcrossDomains, composeChecks, loadAndCompose, loadCluster, detectDomainConflicts, generateClusterTrace } from './compose.js';

package/src/lint-pure.js

@@ -6,6 +6,29 @@
  * Output: { errors: string[], warnings: string[] }
  */
 
+/**
+ * Map of old/informal field names → correct v0.4 spec field names.
+ * Used to give helpful error messages when users write from scratch without the template.
+ */
+const OLD_FIELD_HINTS = {
+  statement: 'one_sentence or full_statement',
+  description: 'one_sentence',
+  summary: 'one_sentence',
+  claim: 'wrong',
+  misreading: 'wrong',
+  reality: 'correct',
+  definition: 'essence or one_sentence (on ontology entries)',
+  brief: 'title or context',
+  bad_pattern: 'what_happened',
+  master_pattern: 'structural_pattern',
+  conclusion: 'one_sentence',
+  capability_layers: 'stages',
+  name: 'id (on ontology entries — use id instead of name)',
+  input: 'from',
+  output: 'to',
+  judgment: 'via',
+};
+
 /**
  * Lint a KDNA domain from a map of parsed JSON objects.
  *
@@ -23,6 +46,15 @@ function lintDomain(dataMap) {
   function req(o, k, loc, hint) {
     if (!has(o, k) || o[k] === '' || o[k] == null) {
       let msg = `${loc}: missing required field "${k}"`;
+      // Check for common old field name and suggest the correct one
+      if (o && typeof o === 'object') {
+        for (const [oldName, newName] of Object.entries(OLD_FIELD_HINTS)) {
+          if (has(o, oldName)) {
+            msg += `\n    → Found field "${oldName}" — this looks like an old/informal field name. Use "${newName}" instead.`;
+            break;
+          }
+        }
+      }
       if (hint) msg += `\n    → ${hint}`;
       errors.push(msg);
     }

package/src/loader.js

@@ -118,6 +118,55 @@ function classifyInput(text) {
   return [...new Set(optional)];
 }
 
+/**
+ * Known field name mapping for detecting old/incorrect field names.
+ * When a common old name is found, log a warning and suggest the correct name.
+ */
+const FIELD_ALIASES = {
+  statement: 'one_sentence or full_statement',
+  description: 'one_sentence',
+  summary: 'one_sentence',
+  claim: 'wrong',
+  misreading: 'wrong',
+  reality: 'correct',
+  definition: 'essence or one_sentence (on ontology)',
+  brief: 'title or context',
+  bad_pattern: 'what_happened',
+  master_pattern: 'structural_pattern',
+  conclusion: 'one_sentence',
+  capability_layers: 'stages',
+  name: 'id (on ontology entries)',
+  input: 'from',
+  output: 'to',
+  judgment: 'via',
+};
+
+/**
+ * Deep-scan an object tree for known old field names and return warnings.
+ * @param {object} obj
+ * @param {string} path
+ * @param {string[]} [warnings]
+ * @returns {string[]}
+ */
+function detectOldFieldNames(obj, path = '', warnings = []) {
+  if (!obj || typeof obj !== 'object') return warnings;
+  if (Array.isArray(obj)) {
+    obj.forEach((item, i) => detectOldFieldNames(item, `${path}[${i}]`, warnings));
+    return warnings;
+  }
+  for (const key of Object.keys(obj)) {
+    if (FIELD_ALIASES[key]) {
+      warnings.push(
+        `[KDNA LOADER] ${path}.${key}: field "${key}" is not in spec v0.4. Use "${FIELD_ALIASES[key]}" instead. See docs/authoring-guide.md §0.`,
+      );
+    }
+    if (typeof obj[key] === 'object' && obj[key] !== null) {
+      detectOldFieldNames(obj[key], `${path}.${key}`, warnings);
+    }
+  }
+  return warnings;
+}
+
 /**
  * Format a loaded KDNA domain into a context string suitable for
  * inclusion in an agent's system prompt.
@@ -132,6 +181,17 @@ function formatContext(domain) {
   const core = domain.core;
   const pat = domain.patterns;
 
+  // Scan for old field names and warn
+  const warnings = detectOldFieldNames(domain, domain.core?.meta?.domain || 'domain');
+  if (warnings.length) {
+    parts.push('<!-- KDNA FIELD NAME WARNINGS:');
+    for (const w of warnings) parts.push(`  ${w}`);
+    parts.push('  These fields will be SILENTLY IGNORED by the loader.');
+    parts.push('  See: docs/authoring-guide.md §0 (Field Name Reference)');
+    parts.push('-->');
+    parts.push('');
+  }
+
   parts.push('## Domain Cognition (KDNA)');
   parts.push(`Domain: ${core.meta.domain}`);
   parts.push('');

package/src/validate-pure.js

@@ -118,7 +118,7 @@ function validateCrossFile(dataMap) {
       if (version === null) {
         version = data.meta.version;
       } else if (data.meta.version !== version) {
-        warnings.push(
+        errors.push(
           `${file}: version "${data.meta.version}" differs from "${version}" in other files`,
         );
       }