@aikdna/kdna-studio-core 1.4.2 → 1.5.0

package/README.md

@@ -1,10 +1,10 @@
 # KDNA Studio Core
 
-**KDNA Studio turns raw human experience into AI-loadable cognitive kernels.**
+**KDNA Studio Core is the judgment asset refinery.** It turns scattered notes, documents, works, and feedback into loadable .kdna judgment assets — not by compressing content, but by distilling the stable judgment patterns embedded within it.
 
-AI may propose judgment candidates. Humans must confirm judgment. Only human-locked judgment can compile into KDNA.
+AI may propose judgment candidates from content analysis. Humans must confirm judgment. Only human-locked judgment can compile into KDNA.
 
-Open-source Studio-compatible authoring kernel for creating trusted `.kdna` assets — JS/npm package. AI can propose. Humans confirm. Only locked judgment compiles.
+Open-source Studio-compatible authoring kernel for creating trusted `.kdna` assets — JS/npm package. Supports two authoring paths: interview-first (expert self-expression) and distillation-first (pattern extraction from existing content). Both end with Human Judgment Lock.
 
 **KDNA Studio Core is the JS authoring kernel.** It is not a UI tool and not a CLI package. It is a pure-logic engine for creating KDNA judgment cards, Human Locks, compiler output, and authoring provenance from JavaScript applications and Studio-compatible tools.
 
@@ -13,6 +13,11 @@ Studio-compatible authoring pipeline that performs human confirmation,
 validation, canonicalization, identity generation, digest computation, signing,
 optional encryption, and provenance recording.
 
+**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
+conforming KDNA runtime assets.
+
 | Library | Language | Role |
 |---------|----------|------|
 | `@aikdna/kdna-cli` | JS/npm | **Operate** KDNA — install, verify, load, compare, publish |
@@ -24,6 +29,9 @@ optional encryption, and provenance recording.
 
 - **Project Model** — `studio.project.json` with full metadata, provenance tracking
 - **Evidence Room** — import raw material (text, markdown, interviews, cases)
+- **Distillation Target** — declare domain category, owner scope, granularity, task scope, include/exclude areas, and load condition before extraction
+- **Evidence Relevance** — classify source material as relevant, weakly relevant, out-of-scope, or split-domain before distillation
+- **Scope Gate** — mark candidates with `scope_fit`, relevance score, and suggested split domain before they can become cards
 - **Judgment Cards** — 8 card types: axiom, ontology, stance, framework, misunderstanding, self_check, banned_term, terminology
 - **Human Lock** — AI proposes, human confirms. Only locked cards compile.
 - **Authoring Provenance** — every compiled manifest records Studio-compatible
@@ -49,6 +57,15 @@ optional encryption, and provenance recording.
 Evidence Room → Judgment Cards → Human Lock → Quality Gate → Compile → Validate → Export
 ```
 
+For distillation-first authoring, the flow starts with an explicit target:
+
+```
+Declare Domain + Scope → Import Evidence → Classify Relevance → Distill Candidates
+  → Scope Gate → Human Review → Promote to Cards → Human Lock → Compile → Export
+```
+
+A single `.kdna` asset should stay scoped to one domain and loading condition. If a task needs several judgment domains, create multiple domain assets and compose them through a KDNA Cluster rather than making one broad file.
+
 ## Install
 
 ```bash
@@ -63,6 +80,17 @@ The command-line authoring entry is a separate package:
 npm install -g @aikdna/kdna-studio-cli
 kdna-studio create my_domain --name @yourscope/my_domain
 kdna-studio import my_domain ./notes.md
+kdna-studio target declare my_domain \
+  --category expression_writing \
+  --scope personal \
+  --granularity core_principles \
+  --task "longform article review" \
+  --include "argument structure,tone,revision" \
+  --exclude "life habits,food preference"
+kdna-studio source classify my_domain
+kdna-studio distill my_domain --candidates candidates.json
+kdna-studio candidate accept my_domain <candidate-id>
+kdna-studio candidate promote my_domain
 kdna-studio card add my_domain axiom \
   --field one_sentence="Judgment principle" \
   --field full_statement="What the agent should do differently" \
@@ -79,15 +107,31 @@ kdna publish dist/my_domain.kdna
 ## Quick Start
 
 ```js
-const { createProject, createCard, lockCard, compileDomain } = require('@aikdna/kdna-studio-core');
+const {
+  project: projectApi,
+  cards: cardApi,
+  distillation
+} = require('@aikdna/kdna-studio-core');
 
 // 1. Create a project
-const project = createProject('writing_judgment', 'domain', {
+const project = projectApi.createProject('writing_judgment', 'domain', {
   author: { name: 'Writing Expert', id: 'writer_001' }
 });
 
+// Optional: declare a distillation target before extracting from evidence.
+const target = distillation.createDistillationTarget({
+  domainName: 'writing_judgment',
+  domainCategory: 'expression_writing',
+  ownerScope: 'personal',
+  granularity: 'core_principles',
+  taskScope: 'longform article diagnosis and revision',
+  includeAreas: ['argument structure', 'reader framing', 'evidence density'],
+  excludeAreas: ['life habits', 'food preference']
+});
+project.distillation_target = target;
+
 // 2. Create judgment cards
-const card = createCard('axiom', {
+const card = cardApi.createCard('axiom', {
   one_sentence: 'Most writing problems are structural, not language-level.',
   full_statement: 'When reviewing content, diagnose structure before language.',
   why: 'Surface polishing on structurally weak content wastes effort.',
@@ -98,18 +142,17 @@ const card = createCard('axiom', {
 project.cards.push(card);
 
 // 3. Human Lock
-const locked = lockCard(card, {
+const locked = cardApi.lockCard(card, {
   by: 'writer_001',
   statement: 'This represents my professional writing judgment.',
   checked: { applies_when: true, does_not_apply_when: true, failure_risk: true }
 });
 
 // 4. Check readiness
-const { checkHumanLockGate, exportProject } = require('@aikdna/kdna-studio-core');
-const gate = checkHumanLockGate(project);
+const gate = projectApi.checkHumanLockGate(project);
 if (!gate.blocked) {
   // 5. Export
-  const json = exportProject(project);
+  const json = projectApi.exportProject(project);
   console.log('Ready to publish');
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-studio-core",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Studio-compatible authoring kernel for Human Lock, compile, and export of trusted .kdna assets.",
   "type": "commonjs",
   "main": "src/index.js",
@@ -24,7 +24,8 @@
     "validate"
   ],
   "dependencies": {
-    "@aikdna/kdna-core": "^0.6.0"
+    "@aikdna/kdna-core": "^0.8.0",
+    "cbor-x": "^1.6.4"
   },
   "engines": {
     "node": ">=18"

package/src/cards/index.js

@@ -66,7 +66,7 @@ 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
+  // Schema gate 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.`);
@@ -75,6 +75,11 @@ function lockCard(card, lockPayload) {
       throw new Error(`Axiom ${card.id} cannot be locked: missing or too-short why. SPEC requires an explanation of failure mode.`);
     }
   }
+  if (card.type === 'misunderstanding') {
+    if (!card.fields?.key_distinction || card.fields.key_distinction.length < 20) {
+      throw new Error(`Misunderstanding ${card.id} cannot be locked: missing or too-short key_distinction. SPEC requires a clear conceptual boundary.`);
+    }
+  }
 
   const lockedCard = { ...card, fields: { ...card.fields } };
   lockedCard.human_lock = {

package/src/compile/index.js

@@ -1,16 +1,15 @@
 /**
  * Compile locked cards into KDNA domain JSON files — SPEC-compatible output.
  *
- * KDNA SPEC v1.0-rc requirements:
- *   - Every file MUST have meta: { version, domain, created, purpose, load_condition }
- *   - Minimum output: KDNA_Core.json + KDNA_Patterns.json
- *   - Maximum 6 KDNA JSON files per domain
- *   - KDNA_Scenarios.json: { meta, scenes[] }
- *   - KDNA_Reasoning.json: { meta, reasoning_chains[] }
- *   - KDNA_Evolution.json: { meta, stages[], capability_layers[], measurements[] }
+ * KDNA Container v2:
+ *   - Judgment content is encoded as CBOR payload (payload.kdnab)
+ *   - Individual KDNA_Core.json etc. are NOT exposed as ZIP entries
+ *   - kdna.json manifest contains metadata only, no judgment content
  *
  * Only locked cards enter compilation. Draft/Revised excluded silently.
  */
+
+const cbor = require('cbor-x');
 const crypto = require('crypto');
 
 function uuidv7() {
@@ -240,8 +239,8 @@ function compileManifest(project, files, identity = null) {
     .digest('hex');
   const manifest = {
     format: 'kdna',
-    format_version: '1.0',
-    spec_version: '1.0-rc',
+    format_version: '2.0',
+    spec_version: '2.0',
     name: project.name,
     domain_id: assetIdentity.domain_id,
     asset_uid: assetIdentity.asset_uid,
@@ -259,6 +258,17 @@ function compileManifest(project, files, identity = null) {
     license: project.license || { type: 'CC-BY-4.0' },
     description: project.release?.description || project.name,
     file_count: kdnaFileCount,
+    container: {
+      type: 'kdna-container-v2',
+      payload: 'payload.kdnab',
+      payload_encoding: 'cbor',
+      payload_schema: 'kdna-payload-v2',
+      payload_digest: `sha256:${crypto.createHash('sha256').update(files['payload.kdnab']).digest('hex')}`,
+    },
+    runtime: {
+      min_runtime_version: '0.3.0',
+      load_contract: 'context-capsule-v1',
+    },
     creator: project.creator_identity ? {
       creator_id: project.creator_identity.creator_id,
       display_name: project.creator_identity.display_name,
@@ -415,12 +425,21 @@ function compileDomain(project) {
   const evolution = compileEvolution(cards, project);
 
   const files = {};
-  files['KDNA_Core.json'] = JSON.stringify(core, null, 2);
-  files['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);
+
+  // ── KDNA Container v2: encode judgment as single CBOR payload ──
+  const payload = {
+    kind: 'kdna.payload',
+    payload_version: '2.0',
+    domain: { name: project.name, version: (project.release && project.release.version) || '0.1.0' },
+    judgment: { core, patterns },
+    profiles: {},
+    integrity: {},
+  };
+  if (scenarios) payload.judgment.scenarios = scenarios;
+  if (cases) payload.judgment.cases = cases;
+  if (reasoning) payload.judgment.reasoning = reasoning;
+  if (evolution) payload.judgment.evolution = evolution;
+  files['payload.kdnab'] = cbor.encode(payload);
 
   // ── KDNA Card (governance metadata) ─────────────────────────────
   // Must be added BEFORE digest computation so it is included in content_digest.
@@ -520,7 +539,7 @@ function generateReadme(project, options = {}) {
 
   if (lockedSelfChecks.length > 0) {
     lines.push('## Eval Score'); lines.push('');
-    lines.push(`- quality_badge: ${tests.filter(t => t.result === 'with_kdna_better').length >= 5 ? 'tested' : 'untested'}`);
+    lines.push(`- quality_badge: ${tests.filter(t => t.result === 'with_kdna_better').length >= 3 ? 'tested' : 'untested'}`);
     lines.push(`- eval cases: ${tests.length}`);
     lines.push('');
   }

package/src/creator-identity.js

@@ -34,9 +34,10 @@ function creatorFingerprint(publicKeyPem) {
 
 /**
  * Generate a new Ed25519 keypair and persist to identityDir.
- * Returns the creator identity object. Does NOT overwrite existing keys.
+ * If passphrase is provided, the private key is encrypted with AES-256-GCM
+ * (key derived via PBKDF2-SHA256). Without passphrase, plaintext with 0o600.
  */
-function initIdentity(displayName, identityDir = null) {
+function initIdentity(displayName, identityDir = null, passphrase = null) {
   const dir = identityDir || defaultIdentityDir();
   fs.mkdirSync(dir, { recursive: true });
 
@@ -55,7 +56,11 @@ function initIdentity(displayName, identityDir = null) {
     privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
   });
 
-  fs.writeFileSync(privateKeyPath, privateKey, { mode: 0o600 });
+  const privateKeyData = passphrase
+    ? encryptPrivateKey(privateKey, passphrase)
+    : privateKey;
+
+  fs.writeFileSync(privateKeyPath, privateKeyData, { mode: 0o600 });
   fs.writeFileSync(publicKeyPath, publicKey, { mode: 0o644 });
 
   const creatorId = creatorFingerprint(publicKey);
@@ -67,6 +72,7 @@ function initIdentity(displayName, identityDir = null) {
     identity_dir: dir,
     created_at: new Date().toISOString(),
     verified: false,
+    encrypted: !!passphrase,
   };
 
   fs.writeFileSync(identityJsonPath, JSON.stringify(identity, null, 2), { mode: 0o644 });
@@ -106,8 +112,9 @@ function loadIdentity(identityDir = null) {
 /**
  * Sign a payload with the creator's Ed25519 private key.
  * Returns the signature in "ed25519:<hex>" format.
+ * If the key is encrypted, passphrase is required.
  */
-function signPayload(payload, identityDir = null) {
+function signPayload(payload, identityDir = null, passphrase = null) {
   const dir = identityDir || defaultIdentityDir();
   const privateKeyPath = path.join(dir, PRIVATE_KEY_FILE);
 
@@ -117,21 +124,134 @@ function signPayload(payload, identityDir = null) {
     );
   }
 
-  const privateKeyPem = fs.readFileSync(privateKeyPath, 'utf8');
+  let privateKeyPem = fs.readFileSync(privateKeyPath, 'utf8');
+  if (isEncryptedKey(privateKeyPem)) {
+    if (!passphrase) throw new Error('Private key is encrypted. Provide --passphrase to sign.');
+    privateKeyPem = decryptPrivateKey(privateKeyPem, passphrase);
+  }
+
   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}`
+ * Sign a Human Lock payload.
+ * If the key is encrypted, passphrase is required.
  */
-function signHumanLock(cardId, statement, judgmentFingerprint, identityDir = null) {
+function signHumanLock(cardId, statement, judgmentFingerprint, identityDir = null, passphrase = null) {
   const lockPayload = [cardId, statement, judgmentFingerprint].join('\n');
-  return signPayload(lockPayload, identityDir);
+  return signPayload(lockPayload, identityDir, passphrase);
+}
+
+// ── Private Key Encryption ────────────────────────────────────────
+
+function encryptPrivateKey(pem, passphrase) {
+  const salt = crypto.randomBytes(16);
+  const key = crypto.pbkdf2Sync(passphrase, salt, 100000, 32, 'sha256');
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const ciphertext = Buffer.concat([cipher.update(Buffer.from(pem)), cipher.final()]);
+  return JSON.stringify({
+    encrypted: true,
+    kdf: 'pbkdf2-sha256',
+    iterations: 100000,
+    salt: salt.toString('base64'),
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+  });
+}
+
+function decryptPrivateKey(envelope, passphrase) {
+  const env = typeof envelope === 'string' ? JSON.parse(envelope) : envelope;
+  if (!env.encrypted) throw new Error('Private key is not encrypted');
+  const key = crypto.pbkdf2Sync(passphrase, Buffer.from(env.salt, 'base64'), env.iterations, 32, 'sha256');
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(env.iv, 'base64'));
+  decipher.setAuthTag(Buffer.from(env.tag, 'base64'));
+  try {
+    return Buffer.concat([decipher.update(Buffer.from(env.ciphertext, 'base64')), decipher.final()]).toString('utf8');
+  } catch (e) {
+    if (e.code === 'ERR_OSSL_EVP_BAD_DECRYPT' || e.message.includes('bad decrypt')) {
+      throw new Error('Wrong passphrase — cannot decrypt private key.');
+    }
+    throw e;
+  }
+}
+
+function isEncryptedKey(content) {
+  try { const o = JSON.parse(content); return o.encrypted === true; }
+  catch { return false; }
+}
+
+// ── Key Rotation ────────────────────────────────────────────────
+
+/**
+ * Rotate the creator's private key. Generates a new Ed25519 keypair,
+ * signs the rotation event with the old key, and saves both.
+ * The old public key is recorded in creator.json under previous_keys.
+ */
+function rotateIdentity(passphrase = null, identityDir = null) {
+  const identity = loadIdentity(identityDir);
+  if (!identity) throw new Error('No identity found. Run identity init first.');
+
+  const dir = identityDir || defaultIdentityDir();
+  const oldPrivPath = path.join(dir, PRIVATE_KEY_FILE);
+  const oldPubPath = path.join(dir, PUBLIC_KEY_FILE);
+
+  if (!fs.existsSync(oldPrivPath) || !fs.existsSync(oldPubPath)) {
+    throw new Error('Key files not found for rotation.');
+  }
+
+  // Decrypt old key if needed
+  let oldPrivatePem = fs.readFileSync(oldPrivPath, 'utf8');
+  if (isEncryptedKey(oldPrivatePem)) {
+    if (!passphrase) throw new Error('Private key is encrypted. Provide passphrase to rotate.');
+    oldPrivatePem = decryptPrivateKey(oldPrivatePem, passphrase);
+  }
+
+  // Generate new keypair
+  const { publicKey: newPub, privateKey: newPriv } = crypto.generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+
+  // Sign rotation event with old key
+  const rotationPayload = [
+    identity.creator_id,
+    creatorFingerprint(newPub),
+    new Date().toISOString(),
+  ].join('\n');
+  const rotationSig = `ed25519:${crypto.sign(null, Buffer.from(rotationPayload), oldPrivatePem).toString('hex')}`;
+
+  // Save new keypair
+  const newPrivData = passphrase ? encryptPrivateKey(newPriv, passphrase) : newPriv;
+  fs.writeFileSync(oldPrivPath, newPrivData, { mode: 0o600 });
+  fs.writeFileSync(oldPubPath, newPub, { mode: 0o644 });
+
+  // Update identity record
+  const newCreatorId = creatorFingerprint(newPub);
+  const identityJson = path.join(dir, IDENTITY_JSON_FILE);
+  let idData = {};
+  try { idData = JSON.parse(fs.readFileSync(identityJson, 'utf8')); } catch {}
+
+  const previousKeys = idData.previous_keys || [];
+  previousKeys.push({
+    creator_id: identity.creator_id,
+    public_key: identity.public_key,
+    rotated_at: new Date().toISOString(),
+    rotation_signature: rotationSig,
+  });
+
+  idData.creator_id = newCreatorId;
+  idData.public_key = newPub;
+  idData.rotated_at = new Date().toISOString();
+  idData.encrypted = !!passphrase;
+  idData.previous_keys = previousKeys;
+
+  fs.writeFileSync(identityJson, JSON.stringify(idData, null, 2), { mode: 0o644 });
+
+  return { ...idData, creator_id: newCreatorId };
 }
 
 /**
@@ -160,5 +280,8 @@ module.exports = {
   loadPublicKey,
   privateKeyPath,
   defaultIdentityDir,
+  encryptPrivateKey,
+  decryptPrivateKey,
+  isEncryptedKey,
   CREATOR_ID_PREFIX,
 };

package/src/distillation/index.js

@@ -0,0 +1,268 @@
+// Domain-First Distillation — Core API
+// Aligned with SOURCE_DISTILLATION_CONTRACT.md v0.2
+
+// ─── Domain Taxonomy ───────────────────────────────────────────────
+
+const DOMAIN_CATEGORIES = Object.freeze({
+  expression_writing: {
+    id: 'expression_writing',
+    displayName: 'Expression & Writing',
+    examples: ['writing_style', 'blog_voice', 'social_media_tone', 'article_structure'],
+  },
+  aesthetic_creation: {
+    id: 'aesthetic_creation',
+    displayName: 'Aesthetic & Creation',
+    examples: ['visual_design', 'video_rhythm', 'cover_art', 'brand_aesthetics'],
+  },
+  professional_field: {
+    id: 'professional_field',
+    displayName: 'Professional Field',
+    examples: ['legal_judgment', 'medical_diagnosis', 'education_standards'],
+  },
+  decision_preference: {
+    id: 'decision_preference',
+    displayName: 'Decision Preference',
+    examples: ['product_decisions', 'investment_criteria', 'prioritization_methods'],
+  },
+  communication_style: {
+    id: 'communication_style',
+    displayName: 'Communication Style',
+    examples: ['client_communication', 'team_management', 'conflict_handling'],
+  },
+  workflow_process: {
+    id: 'workflow_process',
+    displayName: 'Workflow & Process',
+    examples: ['project_reviews', 'meeting_standards', 'sales_followups'],
+  },
+  life_preference: {
+    id: 'life_preference',
+    displayName: 'Life Preference',
+    examples: ['schedule_preferences', 'learning_habits', 'consumption_choices'],
+  },
+  team_organization: {
+    id: 'team_organization',
+    displayName: 'Team & Organization',
+    examples: ['team_brand', 'hiring_criteria', 'service_standards'],
+  },
+});
+
+const OWNER_SCOPES = Object.freeze({
+  personal: {
+    id: 'personal',
+    displayName: 'Personal',
+    description: 'One person\'s individual standards. Extracts personal preferences, boundaries, taste.',
+  },
+  team: {
+    id: 'team',
+    displayName: 'Team',
+    description: 'Shared team conventions. Extracts team-wide standards, agreed practices.',
+  },
+  organization: {
+    id: 'organization',
+    displayName: 'Organization',
+    description: 'Company/organization policies. Extracts organizational values, compliance boundaries.',
+  },
+  field: {
+    id: 'field',
+    displayName: 'Industry / Field',
+    description: 'Industry/profession-wide. Extracts domain expertise beyond any single practitioner.',
+  },
+});
+
+const GRANULARITY_LEVELS = Object.freeze({
+  core_principles: {
+    id: 'core_principles',
+    displayName: 'Core Principles',
+    description: 'High-level axioms and boundaries. Foundational beliefs, what the person consistently prioritizes and rejects.',
+  },
+  concrete_patterns: {
+    id: 'concrete_patterns',
+    displayName: 'Concrete Patterns',
+    description: 'Recurring decision patterns. Specific rules and detectable habits.',
+  },
+  specific_scenarios: {
+    id: 'specific_scenarios',
+    displayName: 'Specific Scenarios',
+    description: 'Scenario-level triggers. Context-specific judgment triggers and responses.',
+  },
+});
+
+const EVIDENCE_RELEVANCE = Object.freeze({
+  relevant: { id: 'relevant', label: 'Relevant' },
+  weakly_relevant: { id: 'weakly_relevant', label: 'Weakly Relevant' },
+  out_of_scope: { id: 'out_of_scope', label: 'Out of Scope' },
+  split_domain: { id: 'split_domain', label: 'Split Domain' },
+});
+
+// ─── Distillation Target ───────────────────────────────────────────
+
+function createDistillationTarget({
+  domainName,
+  domainCategory = 'expression_writing',
+  ownerScope = 'personal',
+  granularity = 'core_principles',
+  taskScope = '',
+  includeAreas = [],
+  excludeAreas = [],
+  loadCondition = '',
+}) {
+  if (!domainName || typeof domainName !== 'string') {
+    throw new Error('domainName is required');
+  }
+  if (!DOMAIN_CATEGORIES[domainCategory]) {
+    throw new Error(`Invalid domainCategory: ${domainCategory}. Must be one of: ${Object.keys(DOMAIN_CATEGORIES).join(', ')}`);
+  }
+  if (!OWNER_SCOPES[ownerScope]) {
+    throw new Error(`Invalid ownerScope: ${ownerScope}`);
+  }
+  if (!GRANULARITY_LEVELS[granularity]) {
+    throw new Error(`Invalid granularity: ${granularity}`);
+  }
+
+  return {
+    id: `tgt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    domain_name: domainName,
+    domain_category: domainCategory,
+    owner_scope: ownerScope,
+    granularity,
+    task_scope: taskScope,
+    include_areas: includeAreas,
+    exclude_areas: excludeAreas,
+    load_condition: loadCondition || `Load when the task involves ${DOMAIN_CATEGORIES[domainCategory].displayName.toLowerCase()} judgment.`,
+    declared_at: new Date().toISOString(),
+  };
+}
+
+function validateDistillationTarget(target) {
+  const errors = [];
+  if (!target || !target.domain_name) errors.push('domain_name is required');
+  if (!DOMAIN_CATEGORIES[target.domain_category]) errors.push(`invalid domain_category: ${target.domain_category}`);
+  if (!OWNER_SCOPES[target.owner_scope]) errors.push(`invalid owner_scope: ${target.owner_scope}`);
+  if (!GRANULARITY_LEVELS[target.granularity]) errors.push(`invalid granularity: ${target.granularity}`);
+  if (!target.task_scope || target.task_scope.trim().length === 0) errors.push('task_scope is required');
+  return { valid: errors.length === 0, errors };
+}
+
+function targetScopeDescription(target) {
+  const cat = DOMAIN_CATEGORIES[target.domain_category];
+  const scope = OWNER_SCOPES[target.owner_scope];
+  const gran = GRANULARITY_LEVELS[target.granularity];
+  return `Domain: ${cat.displayName}. Scope: ${scope.displayName}. Granularity: ${gran.displayName}. Task: ${target.task_scope}. ${target.load_condition}`;
+}
+
+// ─── Scope Gate ────────────────────────────────────────────────────
+
+function applyScopeGate(candidate, target) {
+  const text = `${candidate.one_sentence || ''} ${candidate.full_statement || ''}`.toLowerCase();
+  const domainWords = [target.domain_category, ...(target.include_areas || [])];
+
+  let scopeFit = true;
+  let relevanceScore = 50;
+  let relevanceEvidence = null;
+  let suggestedSplitDomain = null;
+
+  const domainMatch = domainWords.some(w => text.includes(w.toLowerCase()));
+  const excludeMatch = (target.exclude_areas || []).some(w => text.includes(w.toLowerCase()));
+
+  if (domainMatch && !excludeMatch) {
+    scopeFit = true;
+    relevanceScore = 80;
+  } else if (!domainMatch && (target.include_areas || []).length > 0) {
+    scopeFit = false;
+    relevanceScore = 20;
+    relevanceEvidence = 'No match with declared include areas';
+  } else if (excludeMatch) {
+    scopeFit = false;
+    relevanceScore = 10;
+    relevanceEvidence = 'Matched exclude area';
+  }
+
+  if (!scopeFit) {
+    for (const [catId, cat] of Object.entries(DOMAIN_CATEGORIES)) {
+      if (catId !== target.domain_category) {
+        if (text.includes(catId) || text.includes(cat.displayName.toLowerCase())) {
+          suggestedSplitDomain = cat.displayName;
+          break;
+        }
+      }
+    }
+  }
+
+  return {
+    ...candidate,
+    scope_fit: scopeFit,
+    domain_relevance_score: relevanceScore,
+    relevance_evidence: relevanceEvidence,
+    suggested_split_domain: suggestedSplitDomain,
+  };
+}
+
+function candidateStatusSummary(candidates) {
+  let proposed = 0, accepted = 0, rejected = 0, modified = 0, blocked = 0, outOfScope = 0;
+  for (const c of candidates) {
+    if (c.sensitive_content_flag) { blocked++; continue; }
+    if (!c.scope_fit) { outOfScope++; }
+    switch (c.status || c.candidate_status) {
+      case 'proposed': proposed++; break;
+      case 'accepted': accepted++; break;
+      case 'rejected': rejected++; break;
+      case 'modified': modified++; break;
+    }
+  }
+  return { proposed, accepted, rejected, modified, blocked, outOfScope };
+}
+
+// ─── Sensitive Inference Filter ────────────────────────────────────
+
+const SENSITIVE_KEYWORDS = {
+  identity: [
+    'gender identity', 'sexual orientation', 'ethnicity', 'race', 'racial',
+    '性别认同', '性取向', '种族', '民族',
+  ],
+  health: [
+    'medical condition', 'mental health', 'disability', 'diagnosis', 'medication', 'therapy', 'treatment',
+    '疾病', '病史', '诊断', '药物', '治疗', '心理疾病', '精神健康', '残疾', '残障',
+  ],
+  political: [
+    'political affiliation', 'voting', 'activist', 'party member',
+    '政治立场', '党派', '党员', '政治倾向',
+  ],
+  religious: [
+    'religious belief', 'faith', 'church', 'prayer', 'worship', 'spiritual practice',
+    '宗教信仰', '教会', '祈祷', '礼拜', '信教',
+  ],
+  financial: [
+    'income', 'net worth', 'salary', 'debt', 'bank account', 'savings amount',
+    '收入', '工资', '存款', '负债', '资产净值', '银行卡号', '账户余额',
+  ],
+  intimate: [
+    'relationship status', 'marriage', 'divorce', 'family structure',
+    '婚姻状况', '离婚', '家庭结构', '感情状况', '亲密关系',
+  ],
+};
+
+function checkSensitiveContent(text) {
+  const lower = text.toLowerCase();
+  for (const [domain, keywords] of Object.entries(SENSITIVE_KEYWORDS)) {
+    for (const keyword of keywords) {
+      if (lower.includes(keyword.toLowerCase())) {
+        return { flagged: true, reason: `May involve sensitive domain: ${domain}` };
+      }
+    }
+  }
+  return { flagged: false, reason: null };
+}
+
+module.exports = {
+  DOMAIN_CATEGORIES,
+  OWNER_SCOPES,
+  GRANULARITY_LEVELS,
+  EVIDENCE_RELEVANCE,
+  SENSITIVE_KEYWORDS,
+  createDistillationTarget,
+  validateDistillationTarget,
+  targetScopeDescription,
+  applyScopeGate,
+  candidateStatusSummary,
+  checkSensitiveContent,
+};

package/src/index.js

@@ -30,6 +30,7 @@ const provenance = require('./provenance');
 const quality = require('./quality');
 const testlab = require('./testlab');
 const versioning = require('./versioning');
+const distillation = require('./distillation');
 const feynman = require('./cards/feynman');
 const contradiction = require('./quality/contradiction');
 const validateCards = require('./quality/validate-cards');
@@ -46,6 +47,7 @@ module.exports = {
   governance,
   i18n,
   creator: creatorIdentity,
+  distillation,
 
   // Experimental
   evidence,