@aikdna/kdna-studio-core 1.5.2 → 1.5.4

package/README.md

@@ -13,6 +13,22 @@ Studio-compatible authoring pipeline that performs human confirmation,
 validation, canonicalization, identity generation, digest computation, signing,
 optional encryption, and provenance recording.
 
+Studio Core distinguishes authoring compile output from runtime distribution
+output. Authoring compile output may include source entries such as
+`KDNA_Core.json` and `KDNA_Patterns.json` for audit and review. Runtime export
+must produce the canonical KDNA Core v1 distribution shape:
+
+```text
+mimetype
+kdna.json
+payload.kdnab
+checksums.json
+```
+
+Runtime export must validate with `@aikdna/kdna-core` and must plan through the
+LoadPlan contract in `aikdna/kdna`. Studio products must not create app-private
+`.kdna` shapes that Chat or CLI cannot inspect, validate, or plan-load.
+
 **Hard boundary:** Optional encryption, when supported, MUST be represented as
 protected entries inside the `.kdna` container (RFC-0008). App-private encrypted
 envelopes or transfer wrappers that cannot be opened by KDNA Core are NOT
@@ -41,6 +57,8 @@ conforming KDNA runtime assets.
 - **Feynman Restatement** — verify understanding, not just agreement
 - **Quality Gates** — readiness check: draft → structurally_ready → judgment_ready → publish_ready
 - **Compiler** — locked cards → `KDNA_Core.json` + `KDNA_Patterns.json`
+- **Runtime Export** — compiled judgment → canonical `mimetype` +
+  `kdna.json` + `payload.kdnab` + `checksums.json`
 - **Test Lab** — A/B comparison (No KDNA vs Best Prompt vs KDNA)
 - **Provenance** — content fingerprinting, build tracking, audit trail
 
@@ -110,6 +128,8 @@ kdna publish dist/my_domain.kdna
 const {
   project: projectApi,
   cards: cardApi,
+  compile,
+  exportRuntime,
   distillation
 } = require('@aikdna/kdna-studio-core');
 
@@ -151,12 +171,48 @@ const locked = cardApi.lockCard(card, {
 // 4. Check readiness
 const gate = projectApi.checkHumanLockGate(project);
 if (!gate.blocked) {
-  // 5. Export
-  const json = projectApi.exportProject(project);
-  console.log('Ready to publish');
+  // 5. Compile and runtime-export
+  const compiled = compile.compileDomain(project, { strictAuthority: false });
+  const runtimeAsset = exportRuntime.exportRuntimeAsset(project, { compiled });
+  console.log(Object.keys(runtimeAsset.files));
 }
 ```
 
+## Runtime Export Contract
+
+`compile.compileDomain(project)` is an authoring compile step. It returns source
+and evidence artifacts for review, audit, and reports. It is not itself the
+runtime distribution contract.
+
+Use `exportRuntime.exportRuntimeAsset(project)` to produce a KDNA Core v1
+runtime source directory payload:
+
+```js
+const { exportRuntime } = require('@aikdna/kdna-studio-core');
+
+const runtimeAsset = exportRuntime.exportRuntimeAsset(project);
+// runtimeAsset.files contains only:
+// - mimetype
+// - kdna.json
+// - payload.kdnab
+// - checksums.json
+```
+
+The exported files are tested against `@aikdna/kdna-core.validate`. In the OPEN
+workspace they are also tested against the current `aikdna/kdna` LoadPlan
+implementation when available.
+
+Access values are canonicalized for runtime export:
+
+| Studio / legacy value | Runtime value |
+|---|---|
+| `open` | `public` |
+| `protected` | `licensed` |
+| `runtime` | `remote` |
+
+Top-level source JSON entries such as `KDNA_Core.json`, `KDNA_Patterns.json`,
+and `KDNA_CARD.json` must not be present in runtime export output.
+
 ## Card Types (v1.0)
 
 | Type | Compiles to | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-studio-core",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "Official KDNA Studio Core SDK for authoring, locking, compiling, and exporting .kdna judgment assets through the KDNA toolchain.",
   "type": "commonjs",
   "main": "src/index.js",
@@ -24,7 +24,7 @@
     "validate"
   ],
   "dependencies": {
-    "@aikdna/kdna-core": "^0.9.1",
+    "@aikdna/kdna-core": "^0.12.0",
     "cbor-x": "^1.6.4"
   },
   "engines": {
@@ -36,6 +36,6 @@
     "test:all": "npm run lint && npm test"
   },
   "devDependencies": {
-    "@aikdna/kdna-cli": "^0.19.3"
+    "@aikdna/kdna-cli": "^0.26.1"
   }
 }

package/src/compile/index.js

@@ -472,7 +472,14 @@ function compileDomain(project, options = {}) {
     throw err;
   }
 
-  const files = {};
+  const files = {
+    'KDNA_Core.json': JSON.stringify(core, null, 2),
+    'KDNA_Patterns.json': JSON.stringify(patterns, null, 2),
+  };
+  if (scenarios) files['KDNA_Scenarios.json'] = JSON.stringify(scenarios, null, 2);
+  if (cases) files['KDNA_Cases.json'] = JSON.stringify(cases, null, 2);
+  if (reasoning) files['KDNA_Reasoning.json'] = JSON.stringify(reasoning, null, 2);
+  if (evolution) files['KDNA_Evolution.json'] = JSON.stringify(evolution, null, 2);
 
   // Encode judgment as CBOR payload
   const payload = {

package/src/export-runtime/index.js

@@ -0,0 +1,212 @@
+const crypto = require('crypto');
+const { compileDomain } = require('../compile');
+
+const MIMETYPE_V1 = 'application/vnd.kdna.asset';
+
+function json(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function domainIdFromName(name = 'domain') {
+  const base = String(name).includes('/') ? String(name).split('/').pop() : String(name);
+  const normalized = base
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return /^[a-z]/.test(normalized) ? normalized : `domain_${normalized || 'untitled'}`;
+}
+
+function canonicalAccess(value) {
+  if (!value || value === 'open') return 'public';
+  if (value === 'protected') return 'licensed';
+  if (value === 'runtime') return 'remote';
+  return value;
+}
+
+function semverValue(value, fallback = '0.1.0') {
+  const raw = String(value || '').trim();
+  if (/^[0-9]+\.[0-9]+\.[0-9]+([+-].+)?$/.test(raw)) return raw;
+  const twoPart = raw.match(/^([0-9]+)\.([0-9]+)$/);
+  if (twoPart) return `${twoPart[1]}.${twoPart[2]}.0`;
+  return fallback;
+}
+
+function canonicalLineage(lineage) {
+  if (!lineage || typeof lineage !== 'object') return { type: 'original' };
+  const allowed = new Set([
+    'original',
+    'fork',
+    'adaptation',
+    'translation',
+    'private_variant',
+    'organization_variant',
+    'course_variant',
+  ]);
+  if (allowed.has(lineage.type)) return lineage;
+  return {
+    ...lineage,
+    type: 'adaptation',
+    source_lineage_type: lineage.type || 'unknown',
+  };
+}
+
+function sha256Hex(value) {
+  return crypto.createHash('sha256').update(Buffer.isBuffer(value) ? value : Buffer.from(value)).digest('hex');
+}
+
+function buildChecksums(files) {
+  const entries = {
+    'kdna.json': { algorithm: 'sha256', value: sha256Hex(files['kdna.json']) },
+    'payload.kdnab': { algorithm: 'sha256', value: sha256Hex(files['payload.kdnab']) },
+  };
+  const combined = Object.keys(entries)
+    .sort()
+    .map((name) => `${name}:${entries[name].value}`)
+    .join('\n');
+  return {
+    algorithm: 'sha256',
+    manifest_digest: `sha256:${entries['kdna.json'].value}`,
+    payload_digest: `sha256:${entries['payload.kdnab'].value}`,
+    asset_digest: `sha256:${sha256Hex(combined)}`,
+    entries,
+  };
+}
+
+function parseJsonFile(files, name, fallback = null) {
+  if (!files[name]) return fallback;
+  return JSON.parse(files[name]);
+}
+
+function buildPayload(compiled) {
+  const core = parseJsonFile(compiled.files, 'KDNA_Core.json', {});
+  const patterns = parseJsonFile(compiled.files, 'KDNA_Patterns.json', {});
+  const scenarios = parseJsonFile(compiled.files, 'KDNA_Scenarios.json', { scenes: [] });
+  const cases = parseJsonFile(compiled.files, 'KDNA_Cases.json', { cases: [] });
+  const reasoning = parseJsonFile(compiled.files, 'KDNA_Reasoning.json', { reasoning_chains: [] });
+  const evolution = parseJsonFile(compiled.files, 'KDNA_Evolution.json', { changelog: [], version_notes: [] });
+
+  const firstAxiom = Array.isArray(core.axioms) ? core.axioms[0] : null;
+  return {
+    profile: 'judgment-profile-v1',
+    core: {
+      highest_question:
+        core.meta?.load_condition ||
+        firstAxiom?.one_sentence ||
+        `What judgment should be loaded for ${core.meta?.domain || 'this domain'}?`,
+      axioms: Array.isArray(core.axioms) ? core.axioms : [],
+      boundaries: Array.isArray(core.boundaries) ? core.boundaries : [],
+      risk_model: {
+        risks: Array.isArray(core.risks) ? core.risks : [],
+      },
+    },
+    patterns: Array.isArray(patterns.misunderstandings) ? patterns.misunderstandings : [],
+    scenarios: Array.isArray(scenarios.scenes) ? scenarios.scenes : [],
+    cases: Array.isArray(cases.cases) ? cases.cases : [],
+    reasoning: {
+      self_checks: Array.isArray(patterns.self_check) ? patterns.self_check : [],
+      failure_modes: Array.isArray(reasoning.reasoning_chains) ? reasoning.reasoning_chains : [],
+    },
+    evolution: {
+      stages: Array.isArray(evolution.stages) ? evolution.stages : [],
+      evolution_layers: Array.isArray(evolution.evolution_layers) ? evolution.evolution_layers : [],
+      measurement: Array.isArray(evolution.measurement) ? evolution.measurement : [],
+      changelog: Array.isArray(evolution.changelog) ? evolution.changelog : [],
+      version_notes: Array.isArray(evolution.version_notes) ? evolution.version_notes : [],
+    },
+  };
+}
+
+function buildManifest(project, compiled, payloadBytes, options = {}) {
+  const sourceManifest = parseJsonFile(compiled.files, 'kdna.json', {});
+  const access = canonicalAccess(options.access || project.release?.access || sourceManifest.access);
+  const domainId = sourceManifest.domain_id || domainIdFromName(project.name);
+  const now = options.timestamp || sourceManifest.updated_at || sourceManifest.updated || new Date().toISOString();
+  const creator = project.author || sourceManifest.creator || sourceManifest.author || { name: 'Unknown' };
+
+  const manifest = {
+    kdna_version: '1.0',
+    asset_id: options.asset_id || `kdna:studio:${domainId}`,
+    asset_uid: options.asset_uid || `urn:uuid:${sourceManifest.asset_uid || compiled.identity?.asset_uid}`,
+    asset_type: 'domain',
+    title: options.title || project.title || project.name,
+    version: semverValue(sourceManifest.version || project.release?.version, '0.1.0'),
+    judgment_version: semverValue(sourceManifest.judgment_version || project.release?.judgment_version || project.release?.version, '0.1.0'),
+    created_at: options.created_at || sourceManifest.created_at || new Date(project.created || now).toISOString(),
+    updated_at: options.updated_at || now,
+    creator: {
+      name: creator.name || creator.display_name || 'Unknown',
+      id: creator.id || creator.creator_id || undefined,
+    },
+    compatibility: {
+      min_loader_version: '1.0.0',
+      profile: 'judgment-profile-v1',
+    },
+    payload: {
+      path: 'payload.kdnab',
+      encoding: 'json',
+      encrypted: false,
+      digest: `sha256:${sha256Hex(payloadBytes)}`,
+    },
+    access,
+    summary: sourceManifest.description || project.release?.description || project.name,
+    language: project.default_language || sourceManifest.default_language || 'en',
+    languages: project.languages || sourceManifest.languages || ['en'],
+    license: project.license || sourceManifest.license || { type: 'CC-BY-4.0' },
+    keywords: sourceManifest.keywords || [],
+    lineage: canonicalLineage(project.lineage || sourceManifest.lineage),
+    load_contract: {
+      default_profile: 'compact',
+      profiles: {
+        index: { requires_decryption: false, max_tokens_hint: 200 },
+        compact: { requires_decryption: false, max_tokens_hint: 500 },
+        scenario: { requires_decryption: false, selection: 'triggered_sections_only' },
+        full: { requires_decryption: false, intended_for: ['audit', 'reference'] },
+      },
+    },
+    authoring: {
+      compiler: '@aikdna/kdna-studio-core',
+      compiler_version: require('../../package.json').version,
+      source_build_id: compiled.identity?.build_id || sourceManifest.build_id || null,
+      studio_project_digest: sourceManifest.authoring?.studio_project_digest || null,
+      human_lock_required: true,
+      human_lock_count: sourceManifest.authoring?.human_lock_count || compiled.stats?.locked_cards || 0,
+    },
+  };
+
+  if (access === 'licensed') {
+    manifest.entitlement = options.entitlement || { profile: 'local_receipt', offline: true, revocable: true };
+  }
+  if (access === 'remote') {
+    manifest.runtime = options.runtime || { endpoint: null };
+  }
+  return manifest;
+}
+
+function exportRuntimeAsset(project, options = {}) {
+  const compiled = options.compiled || compileDomain(project, options.compile || {});
+  const payload = buildPayload(compiled);
+  const payloadBytes = json(payload);
+  const manifest = buildManifest(project, compiled, payloadBytes, options);
+  const files = {
+    mimetype: MIMETYPE_V1,
+    'kdna.json': json(manifest),
+    'payload.kdnab': payloadBytes,
+  };
+  files['checksums.json'] = json(buildChecksums(files));
+  return {
+    files,
+    manifest,
+    payload,
+    source: compiled,
+  };
+}
+
+module.exports = {
+  MIMETYPE_V1,
+  exportRuntimeAsset,
+  buildPayload,
+  buildManifest,
+  buildChecksums,
+  canonicalAccess,
+  canonicalLineage,
+};

package/src/index.js

@@ -21,6 +21,7 @@ const cards = require('./cards');
 const compile = require('./compile');
 const creatorIdentity = require('./creator-identity');
 const evidence = require('./evidence');
+const exportRuntime = require('./export-runtime');
 const governance = require('./governance');
 const i18n = require('./i18n');
 const packaging = require('./packaging');
@@ -45,6 +46,7 @@ module.exports = {
   provenance,
   pipeline,
   governance,
+  exportRuntime,
   i18n,
   creator: creatorIdentity,
   distillation,

package/src/project/index.js

@@ -10,6 +10,7 @@
 
 const crypto = require('crypto');
 const projectSchema = require('../../schemas/studio.project.schema.json');
+const { CARD_TYPES } = require('../cards');
 const { JUDGMENT_CARD_TYPES, cardJudgmentFingerprint } = require('../judgment-fields');
 
 function createProject(name, type = 'domain', options = {}) {
@@ -152,8 +153,7 @@ function validateProject(project) {
           if (!(req in card)) issues.push('cards[' + i + ']: missing required field "' + req + '"');
         }
         if (card.type !== undefined) {
-          const validTypes = ['axiom', 'ontology', 'misunderstanding', 'boundary', 'self_check', 'risk', 'aesthetic', 'scenario', 'case'];
-          if (!validTypes.includes(card.type)) issues.push('cards[' + i + ']: invalid type "' + card.type + '"');
+          if (!CARD_TYPES.includes(card.type)) issues.push('cards[' + i + ']: invalid type "' + card.type + '"');
         }
         if (card.status !== undefined) {
           const validStates = ['draft', 'revised', 'locked', 'tested', 'published', 'deprecated'];