@aikdna/studio-core 0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@aikdna/studio-core",
+  "version": "0.1.0",
+  "description": "KDNA Studio Core — pure logic library for authoring, validating, and compiling KDNA domain judgment packages.",
+  "type": "commonjs",
+  "main": "src/index.js",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knowledge-dna/kdna-studio.git",
+    "directory": "packages/studio-core"
+  },
+  "dependencies": {
+    "@aikdna/kdna-core": "^0.3.0"
+  },
+  "peerDependencies": {
+    "@aikdna/kdna-cli": ">=0.16.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  }
+}

package/src/cards/feynman.js

@@ -0,0 +1,94 @@
+/**
+ * Feynman Restatement — Verify understanding, not just agreement.
+ *
+ * The Feynman technique: explain a concept in simple terms a non-expert
+ * would understand. This proves the expert truly owns the judgment,
+ * rather than just nodding at an AI proposal.
+ */
+
+function createFeynmanRestatement(card, text) {
+  if (!text || typeof text !== 'string') throw new Error('Feynman restatement text is required');
+  if (text.length < 20) throw new Error('Feynman restatement too short (minimum 20 chars)');
+
+  const restatement = {
+    text,
+    evaluated_at: new Date().toISOString(),
+    score: evaluateRestatementQuality(card, text),
+  };
+
+  return restatement;
+}
+
+function evaluateRestatementQuality(card, text) {
+  const original = card.fields?.one_sentence || card.fields?.essence || card.fields?.wrong || '';
+  const originalLower = original.toLowerCase();
+  const textLower = text.toLowerCase();
+
+  // 1. Not just a repeat — check word overlap ratio
+  const originalWords = new Set(originalLower.split(/\s+/).filter(w => w.length > 3));
+  const textWords = textLower.split(/\s+/).filter(w => w.length > 3);
+  const overlapCount = textWords.filter(w => originalWords.has(w)).length;
+  const overlapRatio = textWords.length > 0 ? overlapCount / textWords.length : 1;
+  const not_just_repeat = overlapRatio < 0.5;
+
+  // 2. Not too abstract — check for concrete words
+  const concreteSignals = ['example', 'instance', 'case', 'scenario', 'when', 'if', 'customer', 'user', 'client', 'team', 'manager', 'project', 'code', 'product', 'meeting', 'email'];
+  const hasConcrete = concreteSignals.some(w => textLower.includes(w));
+  const not_too_abstract = hasConcrete;
+
+  // 3. Has concrete example — check for story-like patterns
+  const storyPatterns = ['when', 'if', 'because', 'so', 'then', 'example', 'imagine', 'suppose', 'consider'];
+  const hasStory = storyPatterns.filter(w => textLower.includes(w)).length >= 2;
+  const has_concrete_example = hasStory;
+
+  // 4. Clarifies boundary — mentions what it's NOT
+  const boundaryWords = ['not', "don't", 'does not', 'cannot', 'unless', 'except', 'only if', 'but not', 'however'];
+  const clarifies_boundary = boundaryWords.some(w => textLower.includes(w));
+
+  // 5. Ordinary person understands — Flesch-like readability check
+  const sentences = text.split(/[.!?]+/).filter(s => s.trim());
+  const avgWordsPerSentence = sentences.length > 0
+    ? sentences.reduce((s, sent) => s + sent.trim().split(/\s+/).length, 0) / sentences.length
+    : 99;
+  const ordinary_person_understands = avgWordsPerSentence < 25;
+
+  const scores = { not_just_repeat, not_too_abstract, has_concrete_example, clarifies_boundary, ordinary_person_understands };
+  const totalScore = Object.values(scores).filter(Boolean).length;
+
+  return {
+    ...scores,
+    total: totalScore,
+    quality: totalScore >= 4 ? 'good' : totalScore >= 3 ? 'acceptable' : 'needs_improvement',
+    detail: {
+      overlap_ratio: Math.round(overlapRatio * 100) + '%',
+      avg_words_per_sentence: Math.round(avgWordsPerSentence),
+    },
+  };
+}
+
+function attachRestatementToLock(card, restatement) {
+  if (!card.human_lock) throw new Error('Card must be locked before attaching Feynman restatement');
+  card.feynman_restatement = restatement;
+  card.audit_log.push({
+    at: new Date().toISOString(),
+    event: 'feynman_restatement',
+    by: card.human_lock.by,
+  });
+  return card;
+}
+
+function validateRestatementCard(card) {
+  const issues = [];
+  if (!card.feynman_restatement) {
+    issues.push({ type: 'missing_feynman', severity: 'warning', message: `${card.id}: missing Feynman restatement (lock is stronger with it)` });
+    return issues;
+  }
+  const fr = card.feynman_restatement;
+  if (!fr.score?.not_just_repeat) issues.push({ type: 'repeat', severity: 'warning', message: `${card.id}: Feynman may just repeat the original text` });
+  if (!fr.score?.not_too_abstract) issues.push({ type: 'abstract', severity: 'warning', message: `${card.id}: Feynman may be too abstract` });
+  if (!fr.score?.clarifies_boundary) issues.push({ type: 'no_boundary', severity: 'warning', message: `${card.id}: Feynman does not explain when this does NOT apply` });
+  if (!fr.score?.ordinary_person_understands) issues.push({ type: 'complex', severity: 'warning', message: `${card.id}: Feynman may be too complex for a non-expert` });
+  return issues;
+}
+
+module.exports = { createFeynmanRestatement, evaluateRestatementQuality, attachRestatementToLock, validateRestatementCard };

package/src/cards/index.js

@@ -0,0 +1,109 @@
+/**
+ * Judgment Card state machine and lifecycle.
+ *
+ * Responsibilities:
+ *   - Card CRUD operations
+ *   - State machine enforcement (Draft → Revised → Locked → Tested → Published → Deprecated)
+ *   - Human Lock protocol
+ *   - Feynman Restatement
+ *   - Audit trail management
+ */
+
+const VALID_STATES = ['draft', 'revised', 'locked', 'tested', 'published', 'deprecated'];
+const CARD_TYPES = ['axiom', 'ontology', 'misunderstanding', 'boundary', 'self_check', 'risk', 'aesthetic', 'scenario', 'case'];
+
+const TRANSITIONS = {
+  draft: ['revised', 'deprecated'],
+  revised: ['locked', 'draft', 'deprecated'],
+  locked: ['tested', 'revised', 'deprecated'],
+  tested: ['published', 'locked', 'deprecated'],
+  published: ['deprecated'],
+  deprecated: [],
+};
+
+function createCard(type, fields = {}, id = null) {
+  if (!CARD_TYPES.includes(type)) throw new Error(`Invalid card type: ${type}`);
+  const card = {
+    id: id || `${type.slice(0, 2)}_${Date.now().toString(36)}`,
+    type,
+    status: 'draft',
+    locked: false,
+    fields,
+    evidence_refs: [],
+    test_refs: [],
+    human_lock: null,
+    feynman_restatement: null,
+    audit_log: [
+      { at: new Date().toISOString(), event: 'created', by: 'ai' }
+    ],
+  };
+  return card;
+}
+
+function transitionCard(card, toState, transitionContext = {}) {
+  if (!VALID_STATES.includes(toState)) throw new Error(`Invalid state: ${toState}`);
+  if (!TRANSITIONS[card.status].includes(toState)) {
+    throw new Error(`Invalid transition: ${card.status} → ${toState}`);
+  }
+  const from = card.status;
+  card.status = toState;
+  card.locked = ['locked', 'tested', 'published'].includes(toState);
+  card.audit_log.push({
+    at: new Date().toISOString(),
+    event: toState,
+    by: transitionContext.by || 'system',
+    ...(transitionContext.reason && { reason: transitionContext.reason }),
+  });
+  return card;
+}
+
+function lockCard(card, lockPayload) {
+  if (!lockPayload.by) throw new Error('lockPayload.by is required');
+  if (!lockPayload.statement) throw new Error('lockPayload.statement is required (expert confirmation in own words)');
+  if (!lockPayload.checked?.applies_when) throw new Error('Must confirm applies_when reviewed');
+  if (!lockPayload.checked?.does_not_apply_when) throw new Error('Must confirm does_not_apply_when reviewed');
+  if (!lockPayload.checked?.failure_risk) throw new Error('Must confirm failure_risk reviewed');
+
+  card.human_lock = {
+    by: lockPayload.by,
+    at: new Date().toISOString(),
+    statement: lockPayload.statement,
+    checked: lockPayload.checked,
+  };
+
+  return transitionCard(card, 'locked', { by: lockPayload.by });
+}
+
+function unlockCard(card, reason, by) {
+  if (!reason) throw new Error('Unlock requires a reason');
+  card.human_lock = null;
+  return transitionCard(card, 'revised', {
+    by,
+    reason: `unlocked: ${reason}`,
+  });
+}
+
+function getLockedCards(project) {
+  return project.cards.filter(c => ['locked', 'tested', 'published'].includes(c.status));
+}
+
+function getPublishableCards(project) {
+  return project.cards.filter(c => c.status === 'tested' || c.status === 'locked');
+}
+
+module.exports = {
+  CARD_TYPES,
+  VALID_STATES,
+  TRANSITIONS,
+  createCard,
+  transitionCard,
+  lockCard,
+  unlockCard,
+  getLockedCards,
+  getPublishableCards,
+  // Feynman restatement (re-exported from feynman.js)
+  createFeynmanRestatement: require('./feynman').createFeynmanRestatement,
+  evaluateRestatementQuality: require('./feynman').evaluateRestatementQuality,
+  attachRestatementToLock: require('./feynman').attachRestatementToLock,
+  validateRestatementCard: require('./feynman').validateRestatementCard,
+};

package/src/cli-bridge/index.js

@@ -0,0 +1 @@
+module.exports = {};

package/src/compile/index.js

@@ -0,0 +1,118 @@
+/**
+ * Compile locked cards into KDNA domain JSON files.
+ *
+ * Only locked cards enter compilation output.
+ * Draft/Revised cards are silently excluded.
+ */
+
+function compileCore(cards) {
+  const axioms = cards.filter(c => c.type === 'axiom' && c.locked).map(c => ({
+    id: c.id,
+    ...c.fields,
+  }));
+  const ontology = cards.filter(c => c.type === 'ontology' && c.locked).map(c => ({
+    id: c.id,
+    ...c.fields,
+  }));
+  const frameworks = [];
+  const stances = [];
+  const boundaries = cards.filter(c => c.type === 'boundary' && c.locked).map(c => ({
+    id: c.id,
+    scope: c.fields.scope,
+    out_of_scope: c.fields.out_of_scope,
+    acceptable_exceptions: c.fields.acceptable_exceptions || [],
+  }));
+
+  const risks = cards.filter(c => c.type === 'risk' && c.locked).map(c => ({
+    id: c.id,
+    failure_mode: c.fields.failure_mode,
+    likelihood: c.fields.likelihood,
+    mitigation: c.fields.mitigation,
+  }));
+
+  return { axioms, ontology, frameworks, stances, boundaries, risks };
+}
+
+function compilePatterns(cards) {
+  const misunderstandings = cards.filter(c => c.type === 'misunderstanding' && c.locked).map(c => ({
+    id: c.id,
+    wrong: c.fields.wrong,
+    correct: c.fields.correct,
+    key_distinction: c.fields.key_distinction,
+    failure_risk: c.fields.failure_risk,
+  }));
+  const selfChecks = cards.filter(c => c.type === 'self_check' && c.locked).map(c => c.fields.question);
+  const bannedTerms = [];
+  const aesthetics = cards.filter(c => c.type === 'aesthetic' && c.locked).map(c => ({
+    id: c.id,
+    preference: c.fields.preference,
+    rationale: c.fields.rationale,
+  }));
+
+  const terminology = {
+    standard_terms: [],
+    banned_terms: bannedTerms,
+  };
+
+  return { terminology, misunderstandings, self_check: selfChecks, aesthetics };
+}
+
+function compileScenarios(cards) {
+  return cards.filter(c => c.type === 'scenario' && c.locked).map(c => ({
+    id: c.id,
+    ...c.fields,
+  }));
+}
+
+function compileCases(cards) {
+  return cards.filter(c => c.type === 'case' && c.locked).map(c => ({
+    id: c.id,
+    ...c.fields,
+  }));
+}
+
+function compileManifest(project) {
+  const lockedCount = project.cards.filter(c => c.locked).length;
+  return {
+    kdna_spec: '1.0-rc',
+    name: project.name,
+    version: project.release?.version || '0.1.0',
+    status: 'experimental',
+    access: project.release?.access || 'open',
+    author: project.author,
+    description: project.release?.description || project.name,
+    file_count: 2, // Core + Patterns minimum
+    created: project.created,
+    updated: project.updated,
+  };
+}
+
+function compileDomain(project) {
+  const cards = project.cards || [];
+  const core = compileCore(cards);
+  const patterns = compilePatterns(cards);
+  const scenarios = compileScenarios(cards);
+  const cases = compileCases(cards);
+  const manifest = compileManifest(project);
+
+  const files = {};
+  files['KDNA_Core.json'] = JSON.stringify(core, null, 2);
+  files['KDNA_Patterns.json'] = JSON.stringify(patterns, null, 2);
+  if (scenarios.length > 0) files['KDNA_Scenarios.json'] = JSON.stringify(scenarios, null, 2);
+  if (cases.length > 0) files['KDNA_Cases.json'] = JSON.stringify(cases, null, 2);
+  files['kdna.json'] = JSON.stringify(manifest, null, 2);
+
+  const excludedCount = (project.cards || []).filter(c => !c.locked && !['deprecated'].includes(c.status)).length;
+
+  return {
+    files,
+    stats: {
+      total_cards: (project.cards || []).length,
+      locked_cards: (project.cards || []).filter(c => c.locked).length,
+      excluded_cards: excludedCount,
+      deprecated_cards: (project.cards || []).filter(c => c.status === 'deprecated').length,
+    },
+  };
+}
+
+module.exports = { compileDomain, compileCore, compilePatterns, compileScenarios, compileCases, compileManifest };

package/src/evidence/index.js

@@ -0,0 +1,81 @@
+/**
+ * Evidence management — import, annotate, and link raw material to judgment cards.
+ *
+ * Evidence proves "there is material here." It does NOT prove "this is judgment."
+ * Spans are extracted text segments that MAY indicate a judgment pattern.
+ */
+
+const crypto = require('crypto');
+
+function createEvidenceEntry(type, title, content, source = 'manual') {
+  return {
+    id: `ev_${Date.now().toString(36)}`,
+    type,
+    title,
+    content_hash: `sha256:${crypto.createHash('sha256').update(content || '').digest('hex')}`,
+    source,
+    imported_at: new Date().toISOString(),
+    spans: [],
+    content: type === 'text' || type === 'chat' ? content : undefined,
+  };
+}
+
+function addEvidence(project, evidence) {
+  project.evidence = project.evidence || [];
+  project.evidence.push(evidence);
+  if (project.stages?.evidence_room) {
+    project.stages.evidence_room.evidence_count = project.evidence.length;
+    project.stages.evidence_room.status = 'in_progress';
+  }
+  return project;
+}
+
+function extractSpan(evidence, start, end, candidatePattern = null) {
+  const text = evidence.content ? evidence.content.slice(start, end) : '';
+  const span = {
+    id: `span_${evidence.id}_${evidence.spans.length}`,
+    text: text.slice(0, 200), // cap at 200 chars
+    start,
+    end,
+    candidate_pattern: candidatePattern,
+    extracted_at: new Date().toISOString(),
+  };
+  evidence.spans.push(span);
+  return span;
+}
+
+function linkEvidenceToCard(evidence, spanId, card) {
+  if (!card.evidence_refs) card.evidence_refs = [];
+  const ref = `${evidence.id}:${spanId}`;
+  if (!card.evidence_refs.includes(ref)) {
+    card.evidence_refs.push(ref);
+  }
+  return card;
+}
+
+function getEvidenceForCard(evidenceEntries, card) {
+  if (!card.evidence_refs) return [];
+  return card.evidence_refs.map(ref => {
+    const [evId, spanId] = ref.split(':');
+    const ev = evidenceEntries.find(e => e.id === evId);
+    if (!ev) return null;
+    const span = spanId ? ev.spans.find(s => s.id === spanId) : null;
+    return { evidence: ev, span };
+  }).filter(Boolean);
+}
+
+function markEvidenceRoomComplete(project) {
+  if (project.stages?.evidence_room) {
+    project.stages.evidence_room.status = 'complete';
+  }
+  return project;
+}
+
+module.exports = {
+  createEvidenceEntry,
+  addEvidence,
+  extractSpan,
+  linkEvidenceToCard,
+  getEvidenceForCard,
+  markEvidenceRoomComplete,
+};

package/src/index.js

@@ -0,0 +1,44 @@
+/**
+ * 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/    .kdna / .kdnae pack adapters
+ *   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 packaging = require('./packaging');
+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');
+
+module.exports = {
+  cards,
+  compile,
+  evidence,
+  packaging,
+  project,
+  provenance,
+  quality,
+  testlab,
+  versioning,
+  feynman,
+  contradiction,
+};

package/src/packaging/index.js

@@ -0,0 +1,73 @@
+/**
+ * Packaging adapter — call kdna-cli for pack, verify, sign, publish operations.
+ *
+ * Studio Core does not re-implement these. It provides structured interfaces
+ * that delegate to kdna-cli subprocess calls.
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+function packDomain(domainDir, outputDir = null) {
+  const args = ['pack', domainDir];
+  if (outputDir) args.push('--output', outputDir);
+  const result = execSync(`kdna ${args.join(' ')}`, { encoding: 'utf8' });
+  return { success: true, output: result.trim() };
+}
+
+function packEncryptedDomain(domainDir, licensePath, outputDir = null) {
+  const args = ['pack', domainDir, '--encrypt', '--license', licensePath];
+  if (outputDir) args.push('--output', outputDir);
+  const result = execSync(`kdna ${args.join(' ')}`, { encoding: 'utf8' });
+  return { success: true, output: result.trim() };
+}
+
+function verifyDomain(domainPath) {
+  try {
+    const result = execSync(`kdna verify ${domainPath} --json`, { encoding: 'utf8' });
+    return JSON.parse(result);
+  } catch (e) {
+    const stdout = (e.stdout || '').toString();
+    try { return JSON.parse(stdout); } catch { return { error: e.message, stdout }; }
+  }
+}
+
+function inspectContainer(filePath) {
+  try {
+    const result = execSync(`kdna inspect ${filePath} --json`, { encoding: 'utf8' });
+    return JSON.parse(result);
+  } catch {
+    return null;
+  }
+}
+
+function signDomain(domainDir, identityDir = null) {
+  // Uses kdna publish --check for signing
+  const args = ['publish', '--check', domainDir];
+  try {
+    const result = execSync(`kdna ${args.join(' ')}`, { encoding: 'utf8', env: { ...process.env } });
+    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 = execSync(`kdna ${args.join(' ')}`, { encoding: 'utf8' });
+    return { success: true, output: result.trim() };
+  } catch (e) {
+    return { success: false, error: e.stderr?.toString() || e.message };
+  }
+}
+
+module.exports = {
+  packDomain,
+  packEncryptedDomain,
+  verifyDomain,
+  inspectContainer,
+  signDomain,
+  generateLicense,
+};

package/src/project/index.js

@@ -0,0 +1,62 @@
+/**
+ * Studio Project lifecycle.
+ *
+ * Responsibilities:
+ *   - Create, load, save, validate Studio Project manifests
+ *   - Manage project-level state transitions
+ *   - Schema validation against studio.project.schema.json
+ */
+
+const projectSchema = require('../../../studio-schemas/studio.project.schema.json');
+
+function createProject(name, type = 'domain', options = {}) {
+  const project = {
+    studio_version: '0.1.0',
+    project_id: `studio_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+    name,
+    type,
+    created: new Date().toISOString().slice(0, 10),
+    updated: new Date().toISOString().slice(0, 10),
+    author: options.author || { name: '', id: '' },
+    status: 'drafting',
+    cards: [],
+    evidence: [],
+    tests: [],
+    stages: {
+      evidence_room: { status: 'pending', evidence_count: 0 },
+      interview_room: { status: 'pending', questions_asked: 0 },
+      judgment_cards: { status: 'pending', locked: 0, total: 0 },
+      test_lab: { status: 'pending', evals_passed: 0, evals_total: 0 },
+      export: { status: 'pending' },
+    },
+  };
+  return project;
+}
+
+function loadProject(json) {
+  const project = typeof json === 'string' ? JSON.parse(json) : json;
+  // TODO: validate against schema
+  return project;
+}
+
+function saveProject(project) {
+  project.updated = new Date().toISOString().slice(0, 10);
+  return JSON.stringify(project, null, 2);
+}
+
+function validateProject(project) {
+  // TODO: full schema validation using ajv + studio.project.schema.json
+  const issues = [];
+  if (!project.name) issues.push('Missing project name');
+  if (!project.type || !['domain', 'cluster'].includes(project.type)) issues.push('Invalid project type');
+  if (!Array.isArray(project.cards)) issues.push('cards must be an array');
+  return { valid: issues.length === 0, issues };
+}
+
+function upgradeProject(project, fromVersion, toVersion) {
+  // TODO: migration logic across studio_version changes
+  project.studio_version = toVersion;
+  return project;
+}
+
+module.exports = { createProject, loadProject, saveProject, validateProject, upgradeProject };

package/src/provenance/index.js

@@ -0,0 +1,35 @@
+/**
+ * Provenance tracking — build metadata and content fingerprinting.
+ *
+ * Every compiled KDNA domain carries provenance proving:
+ *   - Which Studio Core version created it
+ *   - Which project it came from
+ *   - Who authored the locked cards
+ *   - Content tree fingerprint
+ */
+const crypto = require('crypto');
+
+function buildProvenance(project, compiledFiles) {
+  const lockedCards = (project.cards || []).filter(c => c.locked);
+  const tests = project.tests || [];
+
+  // Content fingerprint: hash of all locked card content
+  const cardHashes = lockedCards
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map(c => `${c.id}:${c.fields?.one_sentence || c.fields?.concept || ''}`);
+  const contentFingerprint = crypto.createHash('sha256').update(cardHashes.join('\n')).digest('hex');
+
+  return {
+    studio_core: 'knowledge-dna/kdna-studio',
+    studio_core_version: project.studio_version || '0.1.0',
+    build_id: `build_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
+    project_id: project.project_id,
+    author_id: project.author?.id || '',
+    locked_card_count: lockedCards.length,
+    test_case_count: tests.length,
+    built_at: new Date().toISOString(),
+    content_fingerprint: `sha256:${contentFingerprint}`,
+  };
+}
+
+module.exports = { buildProvenance };