@aikdna/kdna-studio-core 1.3.0

package/src/governance/index.js

@@ -0,0 +1,140 @@
+/**
+ * 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 || [];
+
+  // Check declared risk level first
+  const declared = (project.governance && project.governance.risk_level) || null;
+  if (declared === 'R3') return 'R3';
+
+  // Short-circuit: check each card individually and stop at first high-risk match
+  for (const card of cards) {
+    const fields = card.fields || {};
+    const cardText = [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();
+
+    for (const [category, keywords] of Object.entries(HIGH_RISK_KEYWORDS)) {
+      for (const kw of keywords) {
+        if (cardText.includes(kw)) {
+          if (['medical', 'safety'].includes(category)) return 'R3';
+          if (['legal', 'financial'].includes(category)) return 'R2';
+          if (category === 'decision') return 'R1';
+        }
+      }
+    }
+  }
+
+  // If no high-risk keywords found and R0-R2 declared, trust the declaration
+  if (declared) return declared;
+
+  return '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' });
+  }
+
+  // Compute risk level once, reuse for both riskLevel and detectedLevel
+  const computedLevel = computeRiskLevel(project);
+  const riskLevel = gov.risk_level || computedLevel;
+
+  // Risk level specific checks
+  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 = computedLevel;
+  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/i18n/index.js

@@ -0,0 +1,145 @@
+/**
+ * I18N — Locale overlay creation, validation, and application.
+ *
+ * KDNA domains encode judgment. Localization changes language, not logic.
+ * Overlays translate text fields by referencing canonical IDs.
+ * Structural fields MUST NOT be changed by localization.
+ */
+
+const TEXT_FIELDS = ['one_sentence', 'full_statement', 'why', 'key_distinction', 'wrong', 'correct',
+  'failure_risk', 'essence', 'boundary', 'trigger_signal', 'question', 'scope', 'out_of_scope'];
+const ARRAY_TEXT_FIELDS = ['applies_when', 'does_not_apply_when', 'acceptable_exceptions'];
+
+const VALID_LOCALES = ['en', 'zh-CN', 'zh-TW', 'ja', 'ko', 'fr', 'de'];
+
+function createLocaleOverlay(project, locale) {
+  if (!VALID_LOCALES.includes(locale)) throw new Error(`Invalid locale: ${locale}`);
+
+  const overlay = { locale, base: 'en', spec_version: '1.0-rc', translations: {} };
+  const cards = project.cards || [];
+
+  for (const card of cards) {
+    if (!card.locked) continue;
+    const fields = card.fields || {};
+
+    for (const field of TEXT_FIELDS) {
+      if (fields[field] && typeof fields[field] === 'string' && fields[field].length > 3) {
+        overlay.translations[`${card.id}.${field}`] = `[TODO: ${locale}] ${fields[field]}`;
+      }
+    }
+    for (const field of ARRAY_TEXT_FIELDS) {
+      if (Array.isArray(fields[field])) {
+        fields[field].forEach((val, idx) => {
+          if (val && typeof val === 'string') {
+            overlay.translations[`${card.id}.${field}.${idx}`] = `[TODO: ${locale}] ${val}`;
+          }
+        });
+      }
+    }
+  }
+
+  return overlay;
+}
+
+function validateLocaleOverlay(project, overlay) {
+  const issues = [];
+  const cards = project.cards || [];
+  const cardIds = new Set(cards.map(c => c.id));
+
+  if (!overlay.locale) issues.push({ type: 'missing_locale', severity: 'blocking', message: 'Overlay must declare locale' });
+  if (!overlay.translations || Object.keys(overlay.translations).length === 0) {
+    issues.push({ type: 'empty', severity: 'warning', message: 'Overlay has no translations' });
+    return { valid: false, issues };
+  }
+
+  // Validate referenced IDs exist
+  for (const key of Object.keys(overlay.translations)) {
+    const cardId = key.split('.')[0];
+    if (!cardIds.has(cardId)) {
+      issues.push({ type: 'unknown_id', severity: 'blocking', message: `Overlay references unknown card: ${cardId}` });
+    }
+  }
+
+  // Check for TODO placeholders
+  const todoCount = Object.values(overlay.translations).filter(v => v.includes('[TODO:')).length;
+  if (todoCount > 0) {
+    issues.push({ type: 'incomplete', severity: 'warning', message: `${todoCount} translations still have TODO placeholders` });
+  }
+
+  return { valid: issues.filter(i => i.severity === 'blocking').length === 0, issues };
+}
+
+function applyLocaleOverlay(domainFiles, overlay) {
+  if (!overlay || !overlay.translations) return domainFiles;
+  const localized = { ...domainFiles };
+
+  for (const [filename, content] of Object.entries(localized)) {
+    if (!filename.startsWith('KDNA_')) continue;
+    try {
+      const data = JSON.parse(content);
+      applyOverlayToObject(data, overlay.translations);
+      localized[filename] = JSON.stringify(data, null, 2);
+    } catch { /* skip non-JSON */ }
+  }
+
+  return localized;
+}
+
+function applyOverlayToObject(obj, translations, prefix = '') {
+  for (const key of Object.keys(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (typeof obj[key] === 'string') {
+      if (translations[fullKey] && !translations[fullKey].includes('[TODO:')) {
+        obj[key] = translations[fullKey];
+      }
+    } else if (Array.isArray(obj[key])) {
+      if (obj[key].every(v => typeof v === 'string')) {
+        obj[key] = obj[key].map((v, i) => {
+          const arrayKey = `${fullKey}.${i}`;
+          return (translations[arrayKey] && !translations[arrayKey].includes('[TODO:')) ? translations[arrayKey] : v;
+        });
+      } else {
+        obj[key].forEach((item, i) => {
+          if (typeof item === 'object' && item !== null) {
+            applyOverlayToObject(item, translations, `${fullKey}.${i}`);
+          } else if (item && item.id) {
+            applyOverlayToObject(item, translations, `${fullKey}.${i}`);
+          }
+        });
+      }
+    } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+      applyOverlayToObject(obj[key], translations, fullKey);
+    }
+  }
+}
+
+function computeI18nCoverage(project) {
+  const cards = project.cards || [];
+  const locked = cards.filter(c => c.locked);
+  if (locked.length === 0) return { level: 'L0', coverage: 0, translatable_fields: 0 };
+
+  const totalFields = locked.reduce((sum, c) => {
+    const fields = c.fields || {};
+    let count = 0;
+    for (const f of TEXT_FIELDS) { if (fields[f] && typeof fields[f] === 'string') count++; }
+    for (const f of ARRAY_TEXT_FIELDS) { if (Array.isArray(fields[f])) count += fields[f].filter(v => typeof v === 'string').length; }
+    return sum + count;
+  }, 0);
+
+  // Check overlay for actual translation completion
+  const overlay = project.i18n_overlay || {};
+  const translations = overlay.translations || {};
+  const translatedCount = Object.values(translations).filter(v => typeof v === 'string' && !v.includes('[TODO:')).length;
+
+  const coverage = totalFields > 0 ? Math.round((translatedCount / totalFields) * 100) : 0;
+
+  let level = 'L0';
+  if (totalFields > 0) level = 'L1'; // Has translatable content
+  if (coverage >= 30) level = 'L2';  // Key fields covered
+  if (coverage >= 70) level = 'L3';  // Full coverage
+  if (coverage >= 90 && (project.tests || []).length >= 5) level = 'L4'; // Full coverage + evals
+
+  return { level, coverage: Math.min(100, coverage), translatable_fields: totalFields, translated_fields: translatedCount };
+}
+
+module.exports = { createLocaleOverlay, validateLocaleOverlay, applyLocaleOverlay, computeI18nCoverage, VALID_LOCALES };

package/src/index.js

@@ -0,0 +1,59 @@
+/**
+ * KDNA Studio Core — Pure logic for authoring KDNA domain judgment.
+ *
+ * This is the canonical open-source implementation of the Studio authoring
+ * workflow. Every exported function is pure logic — no UI dependencies.
+ *
+ * Modules:
+ *   project/      Studio Project CRUD, validation, lifecycle
+ *   evidence/     Evidence import, span extraction, card linkage
+ *   cards/        Card state machine, human lock, Feynman restatement
+ *   quality/      Quality gates, readiness scoring
+ *   compile/      Locked cards → KDNA JSON files
+ *   testlab/      Test case model, comparison runner
+ *   provenance/   Build metadata, content fingerprinting
+ *   packaging/    runtime CLI adapters for dev diagnostics and verification
+ *   versioning/   Judgment diff, changelog generation
+ *   cli-bridge/   Adapter to kdna-cli subprocess calls
+ */
+
+const cards = require('./cards');
+const compile = require('./compile');
+const evidence = require('./evidence');
+const governance = require('./governance');
+const i18n = require('./i18n');
+const packaging = require('./packaging');
+const pipeline = require('./pipeline');
+const project = require('./project');
+const provenance = require('./provenance');
+const quality = require('./quality');
+const testlab = require('./testlab');
+const versioning = require('./versioning');
+const feynman = require('./cards/feynman');
+const contradiction = require('./quality/contradiction');
+const validateCards = require('./quality/validate-cards');
+const delta = require('./testlab/delta');
+
+module.exports = {
+  // Stable
+  project,
+  cards,
+  compile,
+  quality,
+  provenance,
+  pipeline,
+  governance,
+  i18n,
+
+  // Experimental
+  evidence,
+  testlab,
+  delta,
+  feynman,
+  contradiction,
+  validateCards,
+  versioning,
+
+  // Internal
+  packaging,
+};

package/src/judgment-fields.js

@@ -0,0 +1,28 @@
+/**
+ * Shared judgment field definitions for Human Lock gate and fingerprinting.
+ * Used by both cards/index.js and project/index.js to avoid circular deps.
+ */
+
+const JUDGMENT_CARD_TYPES = new Set(['axiom', 'boundary', 'risk', 'aesthetic']);
+
+const JUDGMENT_FIELDS = new Set([
+  'one_sentence', 'full_statement', 'why', 'essence', 'boundary',
+  'wrong', 'correct', 'key_distinction', 'question', 'scope',
+  'out_of_scope', 'applies_when', 'does_not_apply_when', 'failure_risk',
+  'acceptable_exceptions', 'trigger_signal', 'when_to_use', 'steps',
+]);
+
+const crypto = require('crypto');
+
+function cardJudgmentFingerprint(card) {
+  const fields = card.fields || {};
+  const relevant = {};
+  for (const key of JUDGMENT_FIELDS) {
+    if (key in fields) relevant[key] = fields[key];
+  }
+  return crypto.createHash('sha256')
+    .update(card.type + ':' + JSON.stringify(relevant, Object.keys(relevant).sort()))
+    .digest('hex');
+}
+
+module.exports = { JUDGMENT_CARD_TYPES, JUDGMENT_FIELDS, cardJudgmentFingerprint };

package/src/packaging/index.js

@@ -0,0 +1,88 @@
+/**
+ * Runtime CLI adapter for dev-source diagnostics and asset verification.
+ *
+ * All subprocess calls use execFileSync (not execSync with string interpolation)
+ * to prevent command injection. Trusted compile/export is implemented by
+ * Studio Core itself and exposed through @aikdna/kdna-studio-cli. kdna-cli is
+ * only called here for dev-source diagnostics and runtime verification.
+ */
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+function packDomain(domainDir, outputDir = null) {
+  return devBundleSource(domainDir, outputDir);
+}
+
+function devBundleSource(domainDir, outputDir = null) {
+  const args = ['dev', 'pack', domainDir];
+  if (outputDir) args.push('--output', outputDir);
+  const result = execFileSync('kdna', args, { encoding: 'utf8', timeout: 60000 });
+  return {
+    success: true,
+    trusted: false,
+    canonical: false,
+    output: result.trim(),
+  };
+}
+
+function packEncryptedDomain(domainDir, licensePath, outputDir = null) {
+  void domainDir;
+  void licensePath;
+  void outputDir;
+  return {
+    success: false,
+    error: 'Encrypted-extension packaging has been removed. Build a licensed .kdna asset and activate it through the entitlement API.',
+  };
+}
+
+function verifyDomain(domainPath) {
+  try {
+    const result = execFileSync('kdna', ['verify', domainPath, '--json'], { encoding: 'utf8', timeout: 30000 });
+    return JSON.parse(result);
+  } catch (e) {
+    const stdout = (e.stdout || '').toString();
+    try { return JSON.parse(stdout); } catch { return { error: e.message, stdout }; }
+  }
+}
+
+function validateDomain(domainPath) {
+  try {
+    const result = execFileSync('kdna', ['dev', 'validate', domainPath], { encoding: 'utf8', timeout: 30000 });
+    return { success: true, output: result.trim() };
+  } catch (e) {
+    return { success: false, error: e.message, stderr: (e.stderr || '').toString() };
+  }
+}
+
+function inspectContainer(filePath) {
+  try {
+    const result = execFileSync('kdna', ['inspect', filePath, '--json'], { encoding: 'utf8', timeout: 15000 });
+    return JSON.parse(result);
+  } catch { return null; }
+}
+
+function signDomain(domainDir) {
+  try {
+    const result = execFileSync('kdna', ['publish', '--check', domainDir], { encoding: 'utf8', timeout: 30000 });
+    return { success: true, output: result.trim() };
+  } catch (e) {
+    return { success: false, error: (e.stderr || '').toString() || e.message };
+  }
+}
+
+function generateLicense(domain, issuedTo, savePath = null) {
+  const args = ['license', 'generate', domain, '--to', issuedTo];
+  if (savePath) args.push('--save', savePath);
+  try {
+    const result = execFileSync('kdna', args, { encoding: 'utf8', timeout: 15000 });
+    return { success: true, output: result.trim() };
+  } catch (e) {
+    return { success: false, error: (e.stderr || '').toString() || e.message };
+  }
+}
+
+module.exports = {
+  packDomain, devBundleSource, packEncryptedDomain, verifyDomain, validateDomain,
+  inspectContainer, signDomain, generateLicense,
+};

package/src/pipeline.js

@@ -0,0 +1,101 @@
+/**
+ * createStudioPipeline(project, options) — Official convenience API.
+ *
+ * Provides the recommended Studio workflow as a single callable pipeline.
+ * Third-party apps should use this instead of manually calling individual modules.
+ *
+ * Stable API (semver guaranteed).
+ */
+
+const { validateProject } = require('./project');
+const { computeReadiness } = require('./quality');
+const { compileDomain, generateReadme } = require('./compile');
+const { buildProvenance } = require('./provenance');
+const { validateAllCards } = require('./quality/validate-cards');
+
+function createStudioPipeline(project, options = {}) {
+  return new StudioPipeline(project, options);
+}
+
+class StudioPipeline {
+  constructor(project, options = {}) {
+    this.project = project;
+    this.options = options;
+    this.results = {};
+  }
+
+  validateProject() { this.results.project_valid = validateProject(this.project); return this; }
+  validateCards() { const cardIssues = validateAllCards(this.project); this.results.card_validation = { total: cardIssues.length, issues: cardIssues }; return this; }
+  computeReadiness() { this.results.readiness = computeReadiness(this.project); return this; }
+  
+  compile() {
+    this.results.compile = compileDomain(this.project);
+    return this;
+  }
+
+  generateReadme(readmeOptions = {}) {
+    this.results.readme = generateReadme(this.project, readmeOptions);
+    return this;
+  }
+
+  buildProvenance() {
+    if (!this.results.compile) throw new Error('Must call compile() before buildProvenance()');
+    this.results.provenance = buildProvenance(this.project, this.results.compile.files);
+    return this;
+  }
+
+  runAll(options = {}) {
+    this.validateProject();
+    this.validateCards();
+    this.computeReadiness();
+    this.compile();
+    if (options.generateReadme !== false) this.generateReadme(options.readmeOptions);
+    if (options.buildProvenance !== false) this.buildProvenance();
+    return this;
+  }
+
+  // ── Getters ─────────────────────────────────────────────────────
+
+  /** @deprecated Use .readiness instead */
+  get readyness() { return this.results.readiness; }
+  get readiness() { return this.results.readiness; }
+  get compiled() { return this.results.compile; }
+  get kdnaFiles() { return this.results.compile?.files || {}; }
+  get isPublishable() { return this.results.readiness?.publishable === true; }
+
+  // ── Output methods ──────────────────────────────────────────────
+
+  /** Flat summary for UI display */
+  toResult() {
+    return {
+      project_valid: this.results.project_valid?.valid === true,
+      card_issues: this.results.card_validation?.total || 0,
+      readiness: this.results.readiness?.grade || 'unknown',
+      publishable: this.results.readiness?.publishable || false,
+      score: this.results.readiness?.score || 0,
+      kdna_files: this.results.compile?.stats?.kdna_files || 0,
+      locked_cards: this.results.compile?.stats?.locked_cards || 0,
+      excluded_cards: this.results.compile?.stats?.excluded_cards || 0,
+      build_id: this.results.provenance?.build_id || null,
+      fingerprint: this.results.provenance?.content_fingerprint || null,
+      blocking: this.results.readiness?.blocking || [],
+      warnings: this.results.readiness?.warnings || [],
+      next_step: this.results.readiness?.next_step || '',
+    };
+  }
+
+  /** Full artifacts: files + readme + provenance + summary */
+  toArtifacts() {
+    const result = this.toResult();
+    return {
+      ...result,
+      files: this.results.compile?.files || {},
+      readme: this.results.readme || '',
+      provenance: this.results.provenance || null,
+      readiness_raw: this.results.readiness || null,
+      card_validation_raw: this.results.card_validation || null,
+    };
+  }
+}
+
+module.exports = { createStudioPipeline };