@aikdna/kdna-studio-core 1.3.3 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-studio-core",
-  "version": "1.3.3",
+  "version": "1.4.1",
   "description": "Studio-compatible authoring kernel for Human Lock, compile, and export of trusted .kdna assets.",
   "type": "commonjs",
   "main": "src/index.js",

package/src/cards/index.js

@@ -66,12 +66,24 @@ function lockCard(card, lockPayload) {
   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');
 
+  // Schema gate: axiom cards MUST have full_statement and why per KDNA SPEC
+  if (card.type === 'axiom') {
+    if (!card.fields?.full_statement || card.fields.full_statement.length < 20) {
+      throw new Error(`Axiom ${card.id} cannot be locked: missing or too-short full_statement. SPEC requires a complete, testable explanation.`);
+    }
+    if (!card.fields?.why || card.fields.why.length < 20) {
+      throw new Error(`Axiom ${card.id} cannot be locked: missing or too-short why. SPEC requires an explanation of failure mode.`);
+    }
+  }
+
   const lockedCard = { ...card, fields: { ...card.fields } };
   lockedCard.human_lock = {
     by: lockPayload.by,
     at: new Date().toISOString(),
     statement: lockPayload.statement,
     checked: lockPayload.checked,
+    creator_id: lockPayload.creator_id || null,
+    signature: lockPayload.signature || null,
     judgment_fingerprint: cardJudgmentFingerprint(lockedCard),
   };
 
@@ -106,6 +118,7 @@ module.exports = {
   unlockCard,
   getLockedCards,
   getPublishableCards,
+  cardJudgmentFingerprint,
   // Feynman restatement (re-exported from feynman.js)
   createFeynmanRestatement: require('./feynman').createFeynmanRestatement,
   evaluateRestatementQuality: require('./feynman').evaluateRestatementQuality,

package/src/compile/index.js

@@ -34,25 +34,38 @@ function stableStringify(value) {
   return JSON.stringify(value);
 }
 
-function canonicalEntryBytes(fileName, content) {
-  if (fileName.endsWith('.json')) {
-    try {
-      return stableStringify(JSON.parse(content));
-    } catch (_) {
-      return content;
-    }
+function canonicalizeJson(name, content) {
+  const obj = JSON.parse(content);
+  if (name === 'kdna.json') {
+    const copy = { ...obj };
+    delete copy.signature;
+    delete copy.asset_digest;
+    delete copy.container_sha256;
+    delete copy.content_digest;
+    return stableStringify(copy);
   }
-  return content;
+  return stableStringify(obj);
 }
 
 function computeContentDigest(files) {
-  const excluded = new Set(['kdna.json', 'signature.json', '.DS_Store']);
+  // Content digest covers canonical judgment content + public asset metadata.
+  // Reports and build-receipt are build evidence, not content — they change with
+  // every build and would cause self-referencing if included.
+  const excluded = new Set(['signature.json', '.DS_Store', 'build-receipt.json']);
   const payload = Object.keys(files)
     .filter(name => !excluded.has(name))
-    .filter(name => !name.startsWith('reports/') && name !== 'build-receipt.json')
+    .filter(name => !name.startsWith('reports/'))
     .sort()
-    .map(name => `${name}\n${canonicalEntryBytes(name, files[name])}`)
-    .join('\n---entry---\n');
+    .map(name => {
+      let content = files[name];
+      if (name === 'mimetype') content = 'application/vnd.aikdna.kdna+zip';
+      const buf = name.endsWith('.json')
+        ? Buffer.from(canonicalizeJson(name, content))
+        : Buffer.from(content);
+      const hash = crypto.createHash('sha256').update(buf).digest('hex');
+      return `${name}:${hash}`;
+    })
+    .join('\n');
   return `sha256:${crypto.createHash('sha256').update(payload).digest('hex')}`;
 }
 
@@ -241,12 +254,19 @@ function compileManifest(project, files, identity = null) {
     license: project.license || { type: 'CC-BY-4.0' },
     description: project.release?.description || project.name,
     file_count: kdnaFileCount,
+    creator: project.creator_identity ? {
+      creator_id: project.creator_identity.creator_id,
+      display_name: project.creator_identity.display_name,
+      public_key: project.creator_identity.public_key,
+      verified: project.creator_identity.verified || false,
+    } : null,
     authoring: {
       created_by: 'kdna-studio-sdk',
       authoring_tool: 'KDNA Studio Core',
       authoring_tool_version: version,
       compiler: '@aikdna/kdna-studio-core',
       compiler_version: version,
+      source_mode: project.source_mode || 'blank',
       asset_uid: assetIdentity.asset_uid,
       project_uid: assetIdentity.project_uid,
       build_id: assetIdentity.build_id,
@@ -259,6 +279,7 @@ function compileManifest(project, files, identity = null) {
       human_confirmed: lockedCards.length > 0,
       compiled_at: assetIdentity.compiled_at,
     },
+    lineage: project.lineage || { type: 'original' },
     created: project.created || new Date().toISOString().slice(0, 10),
     updated: project.updated || new Date().toISOString().slice(0, 10),
   };
@@ -395,9 +416,10 @@ function compileDomain(project) {
   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);
-  const identity = buildAssetIdentity(project, files);
 
   // ── KDNA Card (governance metadata) ─────────────────────────────
+  // Must be added BEFORE digest computation so it is included in content_digest.
+  const identity = buildAssetIdentity(project, files);
   const provenance = require('../provenance').buildProvenance(project, files, identity);
   const { generateKdnaCard } = require('../governance');
   const kdnaCard = generateKdnaCard(project, {}, provenance);
@@ -412,10 +434,14 @@ function compileDomain(project) {
     kdna_files: Object.keys(files).filter(f => f.startsWith('KDNA_')).length,
     total_files: Object.keys(files).length,
   };
-  Object.assign(files, buildReports(project, files, identity, provenance, stats));
+
+  // Compute content_digest once with all files present, BEFORE building reports.
   identity.content_digest = computeContentDigest(files);
   provenance.content_digest = identity.content_digest;
   provenance.content_fingerprint = identity.content_digest;
+
+  // Now build reports/receipt — they will all see the same digest.
+  Object.assign(files, buildReports(project, files, identity, provenance, stats));
   files['reports/provenance-report.json'] = JSON.stringify(provenance, null, 2);
   files['kdna.json'] = JSON.stringify(compileManifest(project, files, identity), null, 2);
   stats.total_files = Object.keys(files).length;

package/src/creator-identity.js

@@ -0,0 +1,164 @@
+/**
+ * Creator Identity — local Ed25519 keypair generation, loading, and signing.
+ *
+ * Creator IDs use the format: "kdna:creator:ed25519:<sha256-of-public-key>"
+ * Private keys are stored in ~/.kdna/identity/ by default.
+ *
+ * This is local-first — no registration, no upload, no cloud dependency.
+ * The private key is the root of creator identity; the public key fingerprint
+ * is the creator_id that appears in studio.project.json and exported .kdna assets.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CREATOR_ID_PREFIX = 'kdna:creator:ed25519:';
+
+function defaultIdentityDir() {
+  return process.env.KDNA_IDENTITY_DIR || path.join(os.homedir(), '.kdna', 'identity');
+}
+
+const PRIVATE_KEY_FILE = 'kdna.key';
+const PUBLIC_KEY_FILE = 'kdna.pub';
+const IDENTITY_JSON_FILE = 'creator.json';
+
+/**
+ * Compute the creator_id fingerprint from an Ed25519 public key PEM.
+ */
+function creatorFingerprint(publicKeyPem) {
+  const hash = crypto.createHash('sha256').update(publicKeyPem).digest('hex');
+  return `${CREATOR_ID_PREFIX}${hash}`;
+}
+
+/**
+ * Generate a new Ed25519 keypair and persist to identityDir.
+ * Returns the creator identity object. Does NOT overwrite existing keys.
+ */
+function initIdentity(displayName, identityDir = null) {
+  const dir = identityDir || defaultIdentityDir();
+  fs.mkdirSync(dir, { recursive: true });
+
+  const privateKeyPath = path.join(dir, PRIVATE_KEY_FILE);
+  const publicKeyPath = path.join(dir, PUBLIC_KEY_FILE);
+  const identityJsonPath = path.join(dir, IDENTITY_JSON_FILE);
+
+  if (fs.existsSync(privateKeyPath) || fs.existsSync(publicKeyPath)) {
+    throw new Error(
+      `Identity keys already exist in ${dir}. Use loadIdentity() to access them, or remove the files to regenerate.`,
+    );
+  }
+
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+
+  fs.writeFileSync(privateKeyPath, privateKey, { mode: 0o600 });
+  fs.writeFileSync(publicKeyPath, publicKey, { mode: 0o644 });
+
+  const creatorId = creatorFingerprint(publicKey);
+  const identity = {
+    creator_id: creatorId,
+    display_name: displayName || '',
+    public_key: publicKey,
+    public_key_path: publicKeyPath,
+    identity_dir: dir,
+    created_at: new Date().toISOString(),
+    verified: false,
+  };
+
+  fs.writeFileSync(identityJsonPath, JSON.stringify(identity, null, 2), { mode: 0o644 });
+
+  return identity;
+}
+
+/**
+ * Load an existing creator identity from disk.
+ * Returns null if no identity has been initialized.
+ */
+function loadIdentity(identityDir = null) {
+  const dir = identityDir || defaultIdentityDir();
+  const identityJsonPath = path.join(dir, IDENTITY_JSON_FILE);
+  const publicKeyPath = path.join(dir, PUBLIC_KEY_FILE);
+
+  if (!fs.existsSync(identityJsonPath)) return null;
+
+  let identity;
+  try {
+    identity = JSON.parse(fs.readFileSync(identityJsonPath, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  // Ensure public key is loaded (may have been deleted from JSON for security)
+  if (!identity.public_key && fs.existsSync(publicKeyPath)) {
+    identity.public_key = fs.readFileSync(publicKeyPath, 'utf8');
+  }
+
+  identity.identity_dir = dir;
+  identity.public_key_path = publicKeyPath;
+
+  return identity;
+}
+
+/**
+ * Sign a payload with the creator's Ed25519 private key.
+ * Returns the signature in "ed25519:<hex>" format.
+ */
+function signPayload(payload, identityDir = null) {
+  const dir = identityDir || defaultIdentityDir();
+  const privateKeyPath = path.join(dir, PRIVATE_KEY_FILE);
+
+  if (!fs.existsSync(privateKeyPath)) {
+    throw new Error(
+      `No private key found at ${privateKeyPath}. Run identity init first.`,
+    );
+  }
+
+  const privateKeyPem = fs.readFileSync(privateKeyPath, 'utf8');
+  const data = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload));
+  const sig = crypto.sign(null, data, privateKeyPem);
+  return `ed25519:${sig.toString('hex')}`;
+}
+
+/**
+ * Sign a Human Lock payload — creates a deterministic signable string from
+ * the lock context and returns the signature.
+ *
+ * Payload: `${cardId}\n${statement}\n${judgmentFingerprint}`
+ */
+function signHumanLock(cardId, statement, judgmentFingerprint, identityDir = null) {
+  const lockPayload = [cardId, statement, judgmentFingerprint].join('\n');
+  return signPayload(lockPayload, identityDir);
+}
+
+/**
+ * Get the public key PEM for the creator identity.
+ */
+function loadPublicKey(identityDir = null) {
+  const dir = identityDir || defaultIdentityDir();
+  const publicKeyPath = path.join(dir, PUBLIC_KEY_FILE);
+  if (!fs.existsSync(publicKeyPath)) return null;
+  return fs.readFileSync(publicKeyPath, 'utf8');
+}
+
+/**
+ * Get the private key path. Used by consumers that need direct key access.
+ */
+function privateKeyPath(identityDir = null) {
+  return path.join(identityDir || defaultIdentityDir(), PRIVATE_KEY_FILE);
+}
+
+module.exports = {
+  initIdentity,
+  loadIdentity,
+  signPayload,
+  signHumanLock,
+  creatorFingerprint,
+  loadPublicKey,
+  privateKeyPath,
+  defaultIdentityDir,
+  CREATOR_ID_PREFIX,
+};

package/src/index.js

@@ -19,6 +19,7 @@
 
 const cards = require('./cards');
 const compile = require('./compile');
+const creatorIdentity = require('./creator-identity');
 const evidence = require('./evidence');
 const governance = require('./governance');
 const i18n = require('./i18n');
@@ -44,6 +45,7 @@ module.exports = {
   pipeline,
   governance,
   i18n,
+  creator: creatorIdentity,
 
   // Experimental
   evidence,

package/src/project/index.js

@@ -22,6 +22,10 @@ function createProject(name, type = 'domain', options = {}) {
     updated: new Date().toISOString().slice(0, 10),
     author: options.author || { name: '', id: '' },
     status: 'drafting',
+    source_mode: options.sourceMode || 'blank',
+    creator_identity: options.creatorIdentity || null,
+    lineage: options.lineage || null,
+    imported_source_folder: options.sourcePath || null,
     cards: [],
     evidence: [],
     tests: [],

package/src/provenance/index.js

@@ -32,6 +32,9 @@ function buildProvenance(project, compiledFiles, identity = {}) {
     domain_id: identity.domain_id || null,
     registry_name: identity.registry_name || project.name || null,
     author_id: project.author?.id || '',
+    creator_id: project.creator_identity?.creator_id || null,
+    source_mode: project.source_mode || 'blank',
+    lineage: project.lineage || { type: 'original' },
     locked_card_count: lockedCards.length,
     test_case_count: tests.length,
     built_at: identity.compiled_at || new Date().toISOString(),

package/src/quality/index.js

@@ -30,6 +30,21 @@ function computeReadiness(project) {
   // ── Governance check (v0.6.1) ───────────────────────────────────
   const govResult = validateGovernance(project);
 
+  // ── Source mode trust checks (v1.4.0) ───────────────────────────
+  const sourceMode = project.source_mode || 'blank';
+  if (sourceMode === 'source_folder') {
+    blocking.push('source_folder: all imported cards must be re-locked — legacy trust is not inherited');
+    blocking.push('source_folder: schema audit required; verify all required fields before Human Lock');
+  }
+  if (sourceMode === 'kdna_asset') {
+    const hasRelevantLineage = project.lineage &&
+      (project.lineage.parent_name || project.lineage.parent_asset_uid);
+    if (!hasRelevantLineage) {
+      blocking.push('kdna_asset: lineage missing — must record parent KDNA identity');
+    }
+    warnings.push('kdna_asset: cards imported from existing KDNA must be re-locked; parent trust is not inherited');
+  }
+
   // ── I18N check (v1.2.0) ─────────────────────────────────────────
   const isOfficial = project.name?.startsWith('@aikdna/') || project.release?.official === true;
   const i18nCoverage = computeI18nCoverage(project);

package/src/quality/validate-cards.js

@@ -77,6 +77,15 @@ function validateAxiom(card, issues) {
     issues.push({ type: 'too_short', severity: 'blocking', message: `${card.id}: one_sentence too short (${oneLiner.length} chars)`, fix: 'Make it a complete, specific judgment statement.' });
   }
 
+  // SPEC requirement: axiom MUST have full_statement and why
+  if (!card.fields?.full_statement || card.fields.full_statement.length < 20) {
+    issues.push({ type: 'missing_full_statement', severity: 'blocking', message: `${card.id}: full_statement missing or too short — SPEC requires a complete, testable explanation`, fix: 'Add a full_statement that is at least 20 characters and explains the principle in full.' });
+  }
+
+  if (!card.fields?.why || card.fields.why.length < 20) {
+    issues.push({ type: 'missing_why', severity: 'blocking', message: `${card.id}: why missing or too short — SPEC requires an explanation of what the agent would get wrong without this axiom`, fix: 'Add a why field that explains the failure mode this axiom prevents.' });
+  }
+
   // Check for dictionary-definition style (axiom should not start with "X is")
   if (/^\w+\s+is\s/.test(oneLiner) && oneLiner.length < 50) {
     issues.push({ type: 'definition_like', severity: 'warning', message: `${card.id}: one_sentence reads like a definition, not a judgment — rephrase as a principle` });