@aikdna/kdna-core 0.2.3 → 0.4.0

package/README.md

@@ -44,6 +44,36 @@ Returns `{ errors: string[], warnings: string[] }`.
 ### `renderDomain(dataMap, options?)`
 Renders domain files into a structured context block using a standard template. The rendered context preserves the domain's structure as distinct, named sections suitable for agent system prompts.
 
+## Compose API (9 functions)
+
+Multi-domain composition — load multiple KDNA domains, classify which should activate for a given input, detect conflicts, and merge their judgment into a single agent context.
+
+### Context Composition
+
+- **`composeContext(domains, options?)`** — Merge multiple loaded domains into a single context string. Conflicting axioms or banned terms from different domains are both included; the agent must report the conflict rather than silently resolve it.
+
+- **`composeContextWithAttribution(domains, options?)`** — Same as `composeContext`, but every axiom, misunderstanding, banned term, and self-check is prefixed with its origin domain (e.g., `[writing:axiom.axiom_problem_not_prose]`). Returns `{ context, attributionMap }`.
+
+- **`loadAndCompose(dataMaps, options?)`** — Convenience function: loads each domain from file data maps, classifies signals against input, then composes the active domains. Returns `{ domains, context, activeIndices }`.
+
+### Signal Classification
+
+- **`classifySignals(input, domains)`** — Match user input against each domain's `trigger_signals`. Returns indices of matching domains. Domains with no signals defined are treated as primary (always active).
+
+- **`classifySignalsAcrossDomains(input, domainEntries)`** — Full diagnostic version of signal classification. Returns `{ selected, excluded }` with reasons (`signal_match`, `required`, `blocked by does_not_apply_when`, `no signal match`).
+
+### Cluster Operations
+
+- **`loadCluster(clusterManifestPath, domainLoader)`** — Load a cluster manifest (`kdna.cluster.json`) and resolve each domain via the provided loader function. Returns `{ manifest, domains, errors }`.
+
+- **`detectDomainConflicts(domains)`** — Detect conflicts between loaded domains in a cluster. Currently checks for: (1) banned term collisions across domains, (2) contradictory stances (simple negation heuristic). Returns array of conflict objects with `type`, `domains`, and `description`.
+
+- **`generateClusterTrace({ input, loadedDomains, activeDomains, conflicts })`** — Generate a judgment trace record for a cluster operation. Returns `{ input, timestamp, loaded_domains, active_domains, active_count, domains_excluded, conflicts }`.
+
+### Utilities
+
+- **`composeChecks(domains)`** — Merge self-check items from multiple domains into a single checklist. Each item is prefixed with its domain name so overlaps are visible.
+
 ## License
 
 Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "KDNA core library — pure logic for loading, validating, linting, and rendering KDNA domain cognition packages. Zero Node.js dependencies.",
   "type": "commonjs",
   "main": "src/index.js",
@@ -15,6 +15,9 @@
     "./schema/*": "./schema/*"
   },
   "types": "src/types.d.ts",
+  "scripts": {
+    "test": "node -e \"const m = require('./src/index.js'); console.log('kdna-core exports:', Object.keys(m).join(', '));\""
+  },
   "files": [
     "src/",
     "schema/",
@@ -24,13 +27,12 @@
     "kdna",
     "kdna-core",
     "ai-agent",
-    "domain-cognition",
-    "knowledge-dna"
+    "domain-cognition"
   ],
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/knowledge-dna/KDNA.git",
+    "url": "git+https://github.com/aikdna/KDNA.git",
     "directory": "packages/kdna-core"
   },
   "homepage": "https://aikdna.com",

package/schema/Composition_Policy.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "KDNA Composition Policy",
+  "description": "Schema for composition.policy.json — defines runtime composition behavior for domain clusters.",
+  "type": "object",
+  "required": ["policy_id", "version"],
+  "properties": {
+    "policy_id": {
+      "type": "string",
+      "description": "Unique policy identifier"
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version of this policy"
+    },
+    "selection_policy": {
+      "type": "object",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["signal_based", "fixed", "staged", "overlay", "user_confirmed"]
+        },
+        "max_domains": { "type": "integer", "minimum": 1 },
+        "min_signal_score": { "type": "number", "minimum": 0, "maximum": 1 },
+        "ask_user_when_ambiguous": { "type": "boolean" }
+      }
+    },
+    "priority_policy": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["when", "domain", "priority", "effect"],
+        "properties": {
+          "when": { "type": "string", "description": "Condition expression triggering this rule" },
+          "domain": { "type": "string", "description": "Domain ID" },
+          "priority": { "type": "integer", "minimum": 0, "maximum": 100 },
+          "effect": {
+            "type": "string",
+            "enum": ["must_include", "block_or_require_confirmation", "deprioritize", "override"]
+          }
+        }
+      }
+    },
+    "conflict_policy": {
+      "type": "object",
+      "properties": {
+        "default": {
+          "type": "string",
+          "enum": ["surface", "priority_wins", "risk_wins", "block", "ask_user", "allow_with_warning"]
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["conflict_type", "action"],
+            "properties": {
+              "conflict_type": {
+                "type": "string",
+                "enum": ["value_conflict", "term_conflict", "risk_conflict", "stance_conflict", "framework_conflict", "output_policy_conflict", "priority_conflict"]
+              },
+              "action": {
+                "type": "string",
+                "enum": ["surface", "surface_and_ask", "risk_wins", "priority_wins", "block", "allow_with_warning"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "merge_policy": {
+      "type": "object",
+      "properties": {
+        "axioms": { "type": "string", "enum": ["include_all_with_source", "dedupe_by_id", "select_by_priority"] },
+        "banned_terms": { "type": "string", "enum": ["union_with_source", "strictest_only", "priority_domain_only"] },
+        "self_checks": { "type": "string", "enum": ["dedupe_by_semantic_similarity", "include_all_with_source", "priority_domain_only"] },
+        "frameworks": { "type": "string", "enum": ["select_by_scenario", "include_all_with_source", "priority_domain_only"] },
+        "stances": { "type": "string", "enum": ["include_conflicts", "priority_domain_only", "merge_with_source"] }
+      }
+    },
+    "output_policy": {
+      "type": "object",
+      "properties": {
+        "must_show_loaded_domains": { "type": "boolean" },
+        "must_record_judgment_trace": { "type": "boolean" },
+        "must_surface_conflicts": { "type": "boolean" },
+        "must_include_uncertainty": { "type": "boolean" }
+      }
+    },
+    "governance": {
+      "type": "object",
+      "properties": {
+        "ownership": {
+          "type": "object",
+          "properties": {
+            "owner_team": { "type": "string" },
+            "maintainers": { "type": "array", "items": { "type": "string" } },
+            "approvers": { "type": "array", "items": { "type": "string" } },
+            "review_cycle": { "type": "string" }
+          }
+        },
+        "lifecycle": {
+          "type": "object",
+          "properties": {
+            "status": { "type": "string", "enum": ["draft", "review", "approved", "active", "deprecated", "archived"] },
+            "effective_from": { "type": "string" },
+            "expires_at": { "type": "string" },
+            "review_required_before": { "type": "string" }
+          }
+        },
+        "change_control": {
+          "type": "object",
+          "properties": {
+            "requires_approval_for": { "type": "array", "items": { "type": "string" } },
+            "minor_changes_allowed_for": { "type": "array", "items": { "type": "string" } },
+            "audit_log_required": { "type": "boolean" }
+          }
+        },
+        "deployment": {
+          "type": "object",
+          "properties": {
+            "environments": { "type": "array", "items": { "type": "string" } },
+            "active_version": { "type": "string" },
+            "rollout_strategy": { "type": "string", "enum": ["manual", "canary", "all_at_once"] },
+            "rollback_version": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/KDNA_Cases.schema.json

@@ -42,8 +42,34 @@
           "outcome": { "type": "string" },
           "kdna_analysis": { "type": "string" },
           "modern_parallel": { "type": "string" },
-          "axiom": { "type": "string" }
-        }
+          "axiom": { "type": "string" },
+          "judgment_path": {
+            "type": "string",
+            "description": "The judgment process applied in this case."
+          },
+          "good_response": {
+            "type": "string",
+            "description": "An example of a good judgment response."
+          },
+          "bad_response": {
+            "type": "string",
+            "description": "An example of a poor judgment response."
+          },
+          "why_good": {
+            "type": "string",
+            "description": "Why the good response aligns with domain judgment."
+          },
+          "why_bad": {
+            "type": "string",
+            "description": "Why the bad response violates domain judgment."
+          },
+          "triggered_axioms": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Axioms triggered by this case."
+          }
+        },
+        "additionalProperties": true
       }
     }
   },

package/schema/KDNA_Cluster.schema.json

@@ -1,53 +1,132 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://aikdna.com/schema/KDNA_Cluster.schema.json",
   "title": "KDNA Cluster Manifest",
-  "description": "Defines a composable group of KDNA packages that work together as a judgment system.",
+  "description": "Schema for kdna.cluster.json — defines a composable judgment system of KDNA domains.",
   "type": "object",
-  "required": ["name", "version", "packages"],
+  "required": ["cluster_id", "name", "version", "domains", "composition"],
   "properties": {
+    "cluster_id": {
+      "type": "string",
+      "description": "Fully qualified cluster identifier, e.g., @company/product-launch-system"
+    },
     "name": {
       "type": "string",
-      "description": "Cluster identifier in lowercase snake_case."
+      "description": "Human-readable cluster name"
     },
     "version": {
       "type": "string",
-      "description": "Semantic version of this cluster."
+      "description": "Semantic version of this cluster manifest"
+    },
+    "description": {
+      "type": "string",
+      "description": "What judgment system this cluster provides"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["horizontal", "vertical", "governance", "enterprise_system"],
+      "description": "Cluster type determining default loading strategy"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "experimental", "stable", "deprecated"]
     },
-    "purpose": {
+    "access": {
       "type": "string",
-      "description": "What complex domain task this cluster addresses."
+      "enum": ["open", "licensed", "runtime"]
     },
-    "packages": {
+    "domains": {
       "type": "array",
-      "description": "KDNA packages that form this cluster.",
-      "minItems": 2,
       "items": {
         "type": "object",
-        "required": ["id", "role"],
+        "required": ["id", "version", "role", "required", "load_condition"],
         "properties": {
-          "id": { "type": "string" },
+          "id": {
+            "type": "string",
+            "description": "Fully qualified domain name (@scope/name)"
+          },
+          "version": {
+            "type": "string",
+            "description": "Semver range, e.g., ^1.2.0"
+          },
           "role": {
             "type": "string",
-            "enum": ["primary", "advisor", "constraint", "critic"]
+            "enum": ["primary", "advisor", "risk_guard", "style_and_trust", "evaluator"]
           },
-          "use_when": {
-            "type": "array",
-            "items": { "type": "string" },
-            "description": "Keywords or conditions that trigger this package."
+          "required": {
+            "type": "boolean",
+            "description": "Whether this domain must load for cluster to function"
+          },
+          "load_condition": {
+            "type": "string",
+            "description": "When this domain should activate"
           }
         }
       }
     },
-    "composition_rules": {
+    "relationships": {
       "type": "array",
-      "items": { "type": "string" },
-      "description": "Rules governing how packages in this cluster interact."
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "type"],
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "type": {
+            "type": "string",
+            "enum": ["depends_on", "constrains", "overrides", "blocks", "informs", "extends", "refines", "conflicts_with", "evaluates", "expressed_through"]
+          },
+          "description": { "type": "string" }
+        }
+      }
     },
-    "routing_questions": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Questions that help the router select the right primary and advisors."
+    "composition": {
+      "type": "object",
+      "required": ["strategy", "conflict_policy", "priority_order"],
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": ["fixed", "signal_based", "staged", "overlay", "user_confirmed"]
+        },
+        "max_active_domains": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "default_domains": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "conflict_policy": {
+          "type": "string",
+          "enum": ["surface", "priority", "block", "ask_user"]
+        },
+        "priority_order": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Ordered list of domain names, highest priority first"
+        }
+      }
+    },
+    "token_budget": {
+      "type": "object",
+      "properties": {
+        "max_context_tokens": { "type": "integer" },
+        "domain_summary_mode": {
+          "type": "string",
+          "enum": ["full", "compact", "axioms_only", "scenario_only"]
+        },
+        "compression_strategy": { "type": "string" }
+      }
+    },
+    "evaluation": {
+      "type": "object",
+      "properties": {
+        "eval_set": { "type": "string" },
+        "minimum_pass_rate": { "type": "number", "minimum": 0, "maximum": 1 },
+        "required_dimensions": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
     }
   }
 }

package/schema/KDNA_Core.schema.json

@@ -40,6 +40,42 @@
       },
       "additionalProperties": true
     },
+    "highest_question": {
+      "type": "string",
+      "description": "The highest-order question this domain answers."
+    },
+    "worldview": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Default assumptions about how the world works in this domain."
+    },
+    "judgment_role": {
+      "type": "object",
+      "properties": {
+        "acts_as": {
+          "type": "string"
+        },
+        "does_not_act_as": {
+          "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } }
+          ]
+        },
+        "responsibility": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "value_order": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Priority ordering of values in this domain."
+    },
     "axioms": {
       "type": "array",
       "items": {
@@ -49,7 +85,46 @@
           "one_sentence",
           "full_statement",
           "why"
-        ]
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "one_sentence": {
+            "type": "string"
+          },
+          "full_statement": {
+            "type": "string"
+          },
+          "why": {
+            "type": "string"
+          },
+          "confidence": {
+            "type": "string"
+          },
+          "evidence_type": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "applies_when": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "does_not_apply_when": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "failure_risk": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
       }
     },
     "ontology": {
@@ -62,7 +137,37 @@
           "essence",
           "boundary",
           "trigger_signal"
-        ]
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "one_sentence": {
+            "type": "string"
+          },
+          "essence": {
+            "type": "string"
+          },
+          "boundary": {
+            "type": "string"
+          },
+          "trigger_signal": {
+            "type": "string"
+          },
+          "applies_when": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "does_not_apply_when": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": true
       }
     },
     "frameworks": {
@@ -74,7 +179,37 @@
           "name",
           "when_to_use",
           "steps"
-        ]
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "when_to_use": {
+            "type": "string"
+          },
+          "steps": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "applies_when": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "does_not_apply_when": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": true
       }
     },
     "core_structure": {
@@ -85,18 +220,67 @@
           "from",
           "to",
           "via"
-        ]
+        ],
+        "properties": {
+          "from": {
+            "type": "string"
+          },
+          "to": {
+            "type": "string"
+          },
+          "via": {
+            "type": "string"
+          },
+          "applies_when": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "does_not_apply_when": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": true
       }
     },
     "stances": {
       "type": "array",
       "items": {
         "anyOf": [
-          { "type": "string" },
-          { "type": "object", "required": ["stance"] }
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "required": [
+              "stance"
+            ],
+            "properties": {
+              "stance": {
+                "type": "string"
+              },
+              "applies_when": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "does_not_apply_when": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "additionalProperties": true
+          }
         ]
       }
     }
   },
   "additionalProperties": true
-}
+}