@aikdna/studio-core 0.5.1 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/studio-core",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "KDNA Studio Core — pure logic library for authoring, validating, and compiling KDNA domain judgment packages.",
   "type": "commonjs",
   "main": "src/index.js",

package/src/compile/index.js

@@ -172,6 +172,14 @@ function compileDomain(project) {
   if (evolution) files['KDNA_Evolution.json'] = JSON.stringify(evolution, null, 2);
   files['kdna.json'] = JSON.stringify(compileManifest(project, files), null, 2);
 
+  // ── KDNA Card (governance metadata) ─────────────────────────────
+  if (project.governance) {
+    const { generateKdnaCard } = require('../governance');
+    const prov = require('../provenance').buildProvenance(project, files);
+    const kdnaCard = generateKdnaCard(project, {}, prov);
+    files['KDNA_CARD.json'] = JSON.stringify(kdnaCard, null, 2);
+  }
+
   const excludedCount = cards.filter(c => !c.locked && !['deprecated'].includes(c.status)).length;
 
   return {

package/src/governance/index.js

@@ -0,0 +1,139 @@
+/**
+ * Governance risk assessment — classify domain risk level and validate governance metadata.
+ *
+ * Risk levels:
+ *   R0 — Low: inconvenience, not harm
+ *   R1 — Medium: suboptimal outcomes
+ *   R2 — High: significant harm possible
+ *   R3 — Restricted: serious harm, not for public registry
+ */
+
+const HIGH_RISK_KEYWORDS = {
+  medical: ['diagnosis', 'treatment', 'symptom', 'patient', 'clinical', 'therapy', 'medication', 'disease', 'prescription', 'surgery', 'medical'],
+  legal: ['lawsuit', 'liability', 'plaintiff', 'defendant', 'jurisdiction', 'statute', 'legal advice', 'attorney', 'court', 'litigation'],
+  financial: ['investment', 'portfolio', 'stock', 'bond', 'retirement', 'insurance', 'mortgage', 'loan', 'tax advice', 'credit score', 'financial advice'],
+  safety: ['weapon', 'surveillance', 'monitoring', 'tracking', 'child safety', 'emergency response', 'public safety', 'self-harm', 'suicide'],
+  decision: ['hiring', 'firing', 'termination', 'employment decision', 'performance review'],
+};
+
+function computeRiskLevel(project) {
+  const cards = project.cards || [];
+  const allText = cards.map(c => {
+    const fields = c.fields || {};
+    return [fields.one_sentence, fields.full_statement, fields.wrong, fields.correct, fields.question,
+      fields.essence, fields.scope, fields.out_of_scope,
+      ...(fields.applies_when || []), ...(fields.does_not_apply_when || [])]
+      .filter(Boolean).join(' ').toLowerCase();
+  }).join(' ');
+
+  // Check declared risk level first
+  const declared = (project.governance && project.governance.risk_level) || null;
+  if (declared === 'R3') return 'R3';
+
+  // Check for high-risk keywords
+  let detectedCategory = null;
+  for (const [category, keywords] of Object.entries(HIGH_RISK_KEYWORDS)) {
+    for (const kw of keywords) {
+      if (allText.includes(kw)) { detectedCategory = category; break; }
+    }
+    if (detectedCategory) break;
+  }
+
+  // If no high-risk keywords found and R0-R2 declared, trust the declaration
+  if (!detectedCategory && declared) return declared;
+
+  // Default risk levels
+  if (['medical', 'safety'].includes(detectedCategory)) return 'R3';
+  if (['legal', 'financial'].includes(detectedCategory)) return 'R2';
+  if (detectedCategory === 'decision') return 'R1';
+
+  return declared || 'R1'; // Default: medium risk
+}
+
+function requiresExpertReview(riskLevel) {
+  return riskLevel === 'R2' || riskLevel === 'R3';
+}
+
+function validateGovernance(project) {
+  const issues = [];
+  const gov = project.governance || {};
+
+  // Required fields
+  if (!gov.risk_level) {
+    issues.push({ type: 'missing_risk_level', severity: 'blocking', message: 'Governance: risk_level must be declared (R0/R1/R2/R3)' });
+  }
+  if (!gov.intended_use || !gov.intended_use.length) {
+    issues.push({ type: 'missing_intended_use', severity: 'blocking', message: 'Governance: intended_use must be declared' });
+  }
+  if (!gov.out_of_scope || !gov.out_of_scope.length) {
+    issues.push({ type: 'missing_out_of_scope', severity: 'blocking', message: 'Governance: out_of_scope must be declared' });
+  }
+  if (!gov.known_limitations || !gov.known_limitations.length) {
+    issues.push({ type: 'missing_limitations', severity: 'blocking', message: 'Governance: known_limitations must be declared' });
+  }
+
+  // Risk level specific checks
+  const riskLevel = gov.risk_level || computeRiskLevel(project);
+  if (requiresExpertReview(riskLevel)) {
+    if (!gov.reviewed_by) {
+      issues.push({ type: 'requires_expert_review', severity: 'blocking', message: `Governance: risk_level ${riskLevel} requires expert_review. reviewed_by must be set.` });
+    }
+    if (!gov.risk_warnings || !gov.risk_warnings.length) {
+      issues.push({ type: 'missing_risk_warnings', severity: 'blocking', message: `Governance: risk_level ${riskLevel} requires risk_warnings.` });
+    }
+  }
+
+  // Check for high-risk keywords in content that might not match declared level
+  const detectedLevel = computeRiskLevel(project);
+  if (gov.risk_level && ['R0', 'R1'].includes(gov.risk_level) && ['R2', 'R3'].includes(detectedLevel)) {
+    issues.push({
+      type: 'risk_mismatch',
+      severity: 'blocking',
+      message: `Governance: declared risk_level ${gov.risk_level} but content analysis suggests ${detectedLevel}. Review required.`,
+    });
+  }
+
+  // Author responsibility required for R1+
+  if (['R1', 'R2', 'R3'].includes(riskLevel) && !gov.author_statement) {
+    issues.push({ type: 'missing_author_statement', severity: 'blocking', message: `Governance: risk_level ${riskLevel} requires author_statement.` });
+  }
+
+  return {
+    valid: issues.filter(i => i.severity === 'blocking').length === 0,
+    issues,
+    risk_level: riskLevel,
+    requires_expert_review: requiresExpertReview(riskLevel),
+  };
+}
+
+function generateKdnaCard(project, compiledStats, provenance) {
+  const gov = project.governance || {};
+  const cards = project.cards || [];
+  const lockedCards = cards.filter(c => c.locked);
+
+  return {
+    name: project.name,
+    version: (project.release && project.release.version) || '0.1.0',
+    risk_level: gov.risk_level || computeRiskLevel(project),
+    intended_use: gov.intended_use || [],
+    out_of_scope: gov.out_of_scope || [],
+    known_limitations: gov.known_limitations || [],
+    author_responsibility: gov.author_statement || '',
+    risk_warnings: gov.risk_warnings || [],
+    human_lock_summary: {
+      locked_cards: lockedCards.length,
+      locked_axioms: lockedCards.filter(c => c.type === 'axiom').length,
+      locked_misunderstandings: lockedCards.filter(c => c.type === 'misunderstanding').length,
+      locked_self_checks: lockedCards.filter(c => c.type === 'self_check').length,
+      feynman_restatements: lockedCards.filter(c => c.feynman_restatement).length,
+      locked_by: (project.author && project.author.id) || 'unknown',
+    },
+    quality_badge: (compiledStats && compiledStats.locked_cards > 0) ? 'tested' : 'untested',
+    review_status: gov.review_status || 'community',
+    requires_expert_review: requiresExpertReview(gov.risk_level || 'R1'),
+    provenance: provenance || {},
+    license: (project.release && project.release.license) || 'CC-BY-4.0',
+  };
+}
+
+module.exports = { computeRiskLevel, requiresExpertReview, validateGovernance, generateKdnaCard, HIGH_RISK_KEYWORDS };

package/src/index.js

@@ -20,6 +20,7 @@
 const cards = require('./cards');
 const compile = require('./compile');
 const evidence = require('./evidence');
+const governance = require('./governance');
 const packaging = require('./packaging');
 const pipeline = require('./pipeline');
 const project = require('./project');
@@ -40,6 +41,7 @@ module.exports = {
   quality,
   provenance,
   pipeline,
+  governance,
 
   // Experimental
   evidence,

package/src/quality/index.js

@@ -12,6 +12,7 @@
 
 const contradiction = require('./contradiction');
 const { validateAllCards } = require('./validate-cards');
+const { validateGovernance } = require('../governance');
 
 function computeReadiness(project) {
   const cards = project.cards || [];
@@ -25,6 +26,12 @@ function computeReadiness(project) {
   const blocking = [];
   const warnings = [];
 
+  // ── Governance check (v0.6.1) ───────────────────────────────────
+  const govResult = validateGovernance(project);
+  for (const issue of govResult.issues) {
+    (issue.severity === 'blocking' ? blocking : warnings).push(`Governance: ${issue.message}`);
+  }
+
   // ── Card validation integration (v0.3.2) ─────────────────────────
   const cardResults = validateAllCards(project);
   for (const { card_id, issues } of cardResults) {
@@ -77,7 +84,7 @@ function computeReadiness(project) {
     grade = 'publishable_grade';
   }
 
-  return buildResult(grade, blocking, warnings, project, { feynmanRatio, allFeynman });
+  return buildResult(grade, blocking, warnings, project, { feynmanRatio, allFeynman, governance: govResult });
 }
 
 function buildResult(grade, blocking, warnings, project, detail = {}) {
@@ -90,6 +97,7 @@ function buildResult(grade, blocking, warnings, project, detail = {}) {
     blocking,
     warnings,
     score: Math.max(0, 100 - blocking.length * 15 - warnings.length * 3),
+    governance: detail.governance || null,
     stats: {
       total_cards: (project.cards || []).length,
       locked_cards: lockedCount,