@aikdna/kdna-studio-core 1.5.0 → 1.5.1

package/README.md

@@ -205,7 +205,7 @@ KDNA Studio Core is open source. Official KDNA Studio App, hosted collaboration,
 
 ## Related
 
-- [KDNA Protocol](https://github.com/aikdna/kdna) — Specification
+- [KDNA Core](https://github.com/aikdna/kdna) — Official format
 - [kdna-cli](https://github.com/aikdna/kdna-cli) — CLI tools
 - [kdna-core-swift](https://github.com/aikdna/kdna-core-swift) — Swift runtime for macOS/iOS
 - [aikdna.com](https://aikdna.com) — Website

package/package.json

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

package/src/cards/index.js

@@ -12,7 +12,7 @@
 const { cardJudgmentFingerprint } = require('../judgment-fields');
 
 const VALID_STATES = ['draft', 'revised', 'locked', 'tested', 'published', 'deprecated'];
-const CARD_TYPES = ['axiom', 'ontology', 'misunderstanding', 'boundary', 'self_check', 'risk', 'aesthetic', 'scenario', 'case'];
+const CARD_TYPES = ['axiom', 'ontology', 'misunderstanding', 'boundary', 'self_check', 'risk', 'aesthetic', 'scenario', 'case', 'stance', 'framework', 'term', 'banned_term', 'reasoning', 'evolution_stage'];
 
 const TRANSITIONS = {
   draft: ['revised', 'deprecated'],

package/src/compile/index.js

@@ -1,7 +1,7 @@
 /**
  * Compile locked cards into KDNA domain JSON files — SPEC-compatible output.
  *
- * KDNA Container v2:
+ * KDNA Container:
  *   - 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
@@ -415,8 +415,28 @@ function buildReports(project, files, identity, provenance, stats) {
   };
 }
 
-function compileDomain(project) {
+function compileDomain(project, options = {}) {
   const cards = project.cards || [];
+
+  // ── Empty-domain gate (PR-2) ────────────────────────────────────
+  // A KDNA domain with no locked judgment content of any kind is not a
+  // domain — it is a content-shaped empty file. Refuse to compile so the
+  // downstream Registry / Lab / Studio export never advertises an empty
+  // judgment asset as "successfully compiled".
+  const lockedCards = cards.filter(c => c.locked);
+  const hasJudgmentContent = lockedCards.some(c =>
+    ['axiom', 'misunderstanding', 'scenario', 'case', 'self_check', 'boundary', 'risk', 'ontology', 'aesthetic'].includes(c.type)
+  );
+  if (!hasJudgmentContent) {
+    const err = new Error(
+      'refusing to compile empty KDNA domain: no locked judgment content ' +
+      `(axiom / misunderstanding / scenario / case / self_check / boundary / risk / ontology / aesthetic). ` +
+      `Found ${lockedCards.length} locked card(s) and ${cards.length} total card(s).`
+    );
+    err.code = 'EMPTY_DOMAIN';
+    throw err;
+  }
+
   const core = compileCore(cards, project);
   const patterns = compilePatterns(cards, project);
   const scenarios = compileScenarios(cards, project);
@@ -424,9 +444,37 @@ function compileDomain(project) {
   const reasoning = compileReasoning(cards, project);
   const evolution = compileEvolution(cards, project);
 
+  // ── RFC-0013 §3.1/§3.2 Compile Gates (PR-3) ───────────────────
+  // Run the Source Authority Graph gate and the Truth Charter gate
+  // BEFORE packaging. PR-2: strictAuthority now defaults to true so
+  // missing/unstable SAG/TC are surfaced as gate errors that block
+  // compilation. Pass options.strictAuthority = false to opt out
+  // (legacy workspaces only).
+  const strictAuthority = options.strictAuthority !== false;
+  const { runSagGate } = require('./source-authority-gate');
+  const { runTcGate } = require('./truth-charter-gate');
+  const sag = runSagGate(options.sourceAuthority, { strict: strictAuthority });
+  const tc = runTcGate(options.truthCharter, {
+    strict: strictAuthority,
+    sourceAuthority: options.sourceAuthority || null,
+    patterns: patterns || null,
+  });
+  const gates = { sag, tc, strict_authority: strictAuthority };
+  // Gate policy: strictAuthority=true + any gate.status === 'fail' => throw.
+  if (strictAuthority && (sag.status === 'fail' || tc.status === 'fail')) {
+    const allErrors = [...sag.errors, ...tc.errors];
+    const err = new Error(
+      `Strict-authority compile failed. ${allErrors.length} gate error(s):\n` +
+        allErrors.map((e) => `  - ${e}`).join('\n'),
+    );
+    err.code = 'GATE_FAIL';
+    err.gates = gates;
+    throw err;
+  }
+
   const files = {};
 
-  // ── KDNA Container v2: encode judgment as single CBOR payload ──
+  // Encode judgment as CBOR payload
   const payload = {
     kind: 'kdna.payload',
     payload_version: '2.0',
@@ -474,6 +522,7 @@ function compileDomain(project) {
     files,
     stats,
     identity,
+    gates,
   };
 }
 
@@ -556,4 +605,4 @@ function generateReadme(project, options = {}) {
   return lines.join('\n');
 }
 
-module.exports = { compileDomain, compileCore, compilePatterns, compileScenarios, compileCases, compileReasoning, compileEvolution, compileManifest, generateReadme, buildAssetIdentity, computeContentDigest };
+module.exports = { compileDomain, compileCore, compilePatterns, compileScenarios, compileCases, compileReasoning, compileEvolution, compileManifest, generateReadme, buildAssetIdentity, computeContentDigest, runSagGate: require('./source-authority-gate').runSagGate, runTcGate: require('./truth-charter-gate').runTcGate };

package/src/compile/source-authority-gate.js

@@ -0,0 +1,156 @@
+/**
+ * Source Authority Graph (SAG) compile gate for kdna-studio-core.
+ *
+ * Implements the SAG gate from RFC-0013 §3.1 / §9 #3.
+ *
+ * Behavior:
+ *   - Default mode: all rules are reported as WARNINGS (soft).
+ *   - Strict-authority mode: hard-rule violations become ERRORS.
+ *   - If no sourceAuthority provided, gate skips silently
+ *     (backwards-compatible: legacy workspaces without SAG pass through).
+ *
+ * Rules checked:
+ *   R1. precedence_order entries must all reference an existing source id.
+ *   R2. At least one source must have authority: "current_highest"
+ *       (when SAG is present; soft warning in default mode).
+ *   R3. authority/status consistency:
+ *         - authority: "deprecated" requires status: "deprecated"
+ *         - authority: "current_highest" requires status: "active"
+ *         - deprecated sources must not appear in precedence_order.
+ *   R4. In precedence_order (highest precedence first), the first
+ *       current_highest must not be preceded by any lower-authority
+ *       source.
+ *   R5. sources_contain_pii=true without author_consent_on_file is
+ *       a soft warning (we are not the consent authority).
+ *
+ * Output contract:
+ *   {
+ *     gate: 'source_authority',
+ *     status: 'skipped' | 'pass' | 'warn' | 'fail',
+ *     errors: [string, ...],   // strict-only; empty in default mode
+ *     warnings: [string, ...], // always populated for any rule
+ *     source_authority: object | null,
+ *     strict_authority: boolean
+ *   }
+ */
+
+const AUTHORITY_RANK = {
+  current_highest: 4,
+  thought_mine: 3,
+  historical_baseline: 2,
+  exemplar_case: 1,
+  deprecated: 0,
+};
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function runSagGate(sourceAuthority, opts = {}) {
+  const strict = !!opts.strict;
+  const result = {
+    gate: 'source_authority',
+    status: 'skipped',
+    errors: [],
+    warnings: [],
+    source_authority: sourceAuthority || null,
+    strict_authority: strict,
+  };
+
+  if (!isPlainObject(sourceAuthority)) {
+    result.status = 'skipped';
+    result.warnings.push('No source_authority.json provided; SAG gate skipped.');
+    return result;
+  }
+
+  // R1. precedence_order references must be valid source ids.
+  const sources = Array.isArray(sourceAuthority.sources) ? sourceAuthority.sources : [];
+  const sourceIds = new Set();
+  for (const s of sources) {
+    if (isPlainObject(s) && typeof s.id === 'string') {
+      sourceIds.add(s.id);
+    }
+  }
+  const order = Array.isArray(sourceAuthority.precedence_order) ? sourceAuthority.precedence_order : [];
+  const missing = order.filter((id) => !sourceIds.has(id));
+  if (missing.length > 0) {
+    const msg = `source_authority.json: precedence_order references unknown source id(s): ${missing.join(', ')}.`;
+    if (strict) result.errors.push(msg);
+    else result.warnings.push(msg);
+  }
+
+  // R2. At least one current_highest source.
+  const highest = sources.filter(
+    (s) => isPlainObject(s) && s.authority === 'current_highest',
+  );
+  if (highest.length === 0) {
+    const msg = 'source_authority.json: no source has authority "current_highest"; at least one current_highest source is required to establish current authority.';
+    if (strict) result.errors.push(msg);
+    else result.warnings.push(msg);
+  }
+
+  // R3. authority/status consistency.
+  for (const s of sources) {
+    if (!isPlainObject(s)) continue;
+    if (s.authority === 'deprecated' && s.status !== 'deprecated') {
+      const msg = `source_authority.json: source "${s.id}" has authority "deprecated" but status is "${s.status}"; status MUST be "deprecated" when authority is "deprecated".`;
+      if (strict) result.errors.push(msg);
+      else result.warnings.push(msg);
+    }
+    if (s.authority === 'current_highest' && s.status !== 'active') {
+      const msg = `source_authority.json: source "${s.id}" has authority "current_highest" but status is "${s.status}"; status MUST be "active" for current_highest sources.`;
+      if (strict) result.errors.push(msg);
+      else result.warnings.push(msg);
+    }
+    if (s.authority === 'deprecated' && order.includes(s.id)) {
+      const msg = `source_authority.json: deprecated source "${s.id}" appears in precedence_order; deprecated sources cannot be authoritative precursors.`;
+      if (strict) result.errors.push(msg);
+      else result.warnings.push(msg);
+    }
+  }
+
+  // R4. In precedence_order, the first current_highest must not be
+  // preceded by any lower-authority source.
+  if (order.length > 0 && highest.length > 0) {
+    const firstHighestIdx = Math.min(
+      ...order
+        .map((id, i) => ({ id, i, isHighest: highest.some((h) => h.id === id) }))
+        .filter((e) => e.isHighest)
+        .map((e) => e.i),
+    );
+    if (Number.isFinite(firstHighestIdx)) {
+      for (let i = 0; i < firstHighestIdx; i++) {
+        const id = order[i];
+        const src = sources.find((s) => isPlainObject(s) && s.id === id);
+        if (!src) continue;
+        if (
+          AUTHORITY_RANK[src.authority] !== undefined &&
+          AUTHORITY_RANK[src.authority] < AUTHORITY_RANK.current_highest
+        ) {
+          const msg = `source_authority.json: lower-authority source "${src.id}" (${src.authority}) appears before current_highest in precedence_order; current_highest must override.`;
+          if (strict) result.errors.push(msg);
+          else result.warnings.push(msg);
+        }
+      }
+    }
+  }
+
+  // R5. PII without consent is a soft warning only.
+  const sensitivity = sourceAuthority.sensitivity || {};
+  if (sensitivity.sources_contain_pii === true && sensitivity.author_consent_on_file !== true) {
+    result.warnings.push(
+      'source_authority.json: sensitivity.sources_contain_pii is true but author_consent_on_file is not true; recording author consent is recommended before publishing.',
+    );
+  }
+
+  if (result.errors.length > 0) {
+    result.status = 'fail';
+  } else if (result.warnings.length > 0) {
+    result.status = 'warn';
+  } else {
+    result.status = 'pass';
+  }
+  return result;
+}
+
+module.exports = { runSagGate, AUTHORITY_RANK };

package/src/compile/truth-charter-gate.js

@@ -0,0 +1,157 @@
+/**
+ * Truth Charter (TC) compile gate for kdna-studio-core.
+ *
+ * Implements the TC gate from RFC-0013 §3.2 / §9 #3.
+ *
+ * Behavior:
+ *   - Default mode: WARNING only. Errors are downgraded to warnings.
+ *   - Strict-authority mode: ERROR for synthesized/draft/deprecated
+ *     tc_status; PASS only for tc_status: "locked".
+ *   - If no truthCharter provided, gate skips silently
+ *     (backwards-compatible: legacy workspaces without TC pass through).
+ *
+ * Rules checked:
+ *   R1. tc_status must be one of: draft / synthesized / locked / deprecated.
+ *   R2. tc_status: "synthesized" + strict-authority -> ERROR
+ *       (synthesized means no real author-locked truth; cannot be
+ *       officially published without explicit lock).
+ *   R3. tc_status: "deprecated" + strict-authority -> ERROR
+ *       (deprecated charters cannot govern new compilations).
+ *   R4. tc_status: "locked" requires locked_at and locked_by fields.
+ *   R5. renamed_terms: if renamed_terms are present and a
+ *       patterns.terminology is supplied, check that each old term is
+ *       either in banned_terms or its replacement is in standard_terms.
+ *       (Soft check; mismatches are warnings, not errors.)
+ *   R6. forbidden_simplifications: presence is recorded; we do NOT
+ *       perform LLM-based semantic verification (would require a
+ *       judgment call outside the gate's scope). Always PASS.
+ *
+ * Cross-file consistency (when both SAG and TC are supplied):
+ *   If sourceAuthority has any current_highest source of type
+ *   "human_locked_charter" and TC exists, TC.judgment_authority_holder
+ *   must be present and non-empty.
+ */
+
+const VALID_TC_STATUS = ['draft', 'synthesized', 'locked', 'deprecated'];
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function runTcGate(truthCharter, opts = {}) {
+  const strict = !!opts.strict;
+  const sourceAuthority = opts.sourceAuthority || null;
+  const patterns = opts.patterns || null; // KDNA_Patterns.json content
+  const result = {
+    gate: 'truth_charter',
+    status: 'skipped',
+    errors: [],
+    warnings: [],
+    truth_charter: truthCharter || null,
+    strict_authority: strict,
+  };
+
+  if (!isPlainObject(truthCharter)) {
+    result.status = 'skipped';
+    result.warnings.push('No truth_charter.json provided; TC gate skipped.');
+    return result;
+  }
+
+  // R1. tc_status must be valid.
+  const tcStatus = truthCharter.tc_status;
+  if (!VALID_TC_STATUS.includes(tcStatus)) {
+    result.errors.push(
+      `truth_charter.json: tc_status "${tcStatus}" is not one of [${VALID_TC_STATUS.join(', ')}].`,
+    );
+    result.status = 'fail';
+    return result;
+  }
+
+  // R2. synthesized + strict -> ERROR.
+  if (tcStatus === 'synthesized') {
+    const msg = 'truth_charter.json: tc_status is "synthesized" (no author-locked truth); strict-authority requires "locked".';
+    if (strict) result.errors.push(msg);
+    else result.warnings.push(msg);
+  }
+
+  // R3. deprecated + strict -> ERROR.
+  if (tcStatus === 'deprecated') {
+    const msg = 'truth_charter.json: tc_status is "deprecated"; deprecated charters cannot govern new compilations under strict-authority.';
+    if (strict) result.errors.push(msg);
+    else result.warnings.push(msg);
+  }
+
+  // R4. locked requires locked_at and locked_by.
+  if (tcStatus === 'locked') {
+    if (!truthCharter.locked_at || !truthCharter.locked_by) {
+      result.errors.push(
+        'truth_charter.json: tc_status is "locked" but locked_at or locked_by is missing.',
+      );
+    }
+  }
+
+  // R5. renamed_terms soft check against patterns.terminology.
+  // Only fires when the project's terminology actually has content; an
+  // empty terminology (from a card-only project) is treated as
+  // "not yet declared" and the soft check is skipped.
+  if (
+    Array.isArray(truthCharter.renamed_terms) &&
+    isPlainObject(patterns) &&
+    isPlainObject(patterns.terminology) &&
+    (Array.isArray(patterns.terminology.standard_terms) && patterns.terminology.standard_terms.length > 0 ||
+      Array.isArray(patterns.terminology.banned_terms) && patterns.terminology.banned_terms.length > 0)
+  ) {
+    const term = patterns.terminology;
+    const banned = new Set(
+      Array.isArray(term.banned_terms) ? term.banned_terms.map((t) => t && t.term).filter(Boolean) : [],
+    );
+    const standard = new Set(
+      Array.isArray(term.standard_terms) ? term.standard_terms.map((t) => t && t.term).filter(Boolean) : [],
+    );
+    for (const r of truthCharter.renamed_terms) {
+      if (!isPlainObject(r)) continue;
+      const oldName = r.old;
+      const newName = r.new;
+      const oldBanned = oldName && banned.has(oldName);
+      const newStandard = newName && standard.has(newName);
+      if (oldName && !oldBanned) {
+        result.warnings.push(
+          `truth_charter.json renamed_terms: old term "${oldName}" is not in KDNA_Patterns.json.terminology.banned_terms; consider adding it to make the rename enforceable.`,
+        );
+      }
+      if (newName && !newStandard) {
+        result.warnings.push(
+          `truth_charter.json renamed_terms: new term "${newName}" is not in KDNA_Patterns.json.terminology.standard_terms; consider adding it.`,
+        );
+      }
+    }
+  }
+
+  // Cross-file consistency: SAG has human_locked_charter current_highest
+  // => TC.judgment_authority_holder must be present and non-empty.
+  if (sourceAuthority && isPlainObject(sourceAuthority)) {
+    const sources = Array.isArray(sourceAuthority.sources) ? sourceAuthority.sources : [];
+    const hasHumanLockedCharter = sources.some(
+      (s) => isPlainObject(s) && s.authority === 'current_highest' && s.type === 'human_locked_charter',
+    );
+    if (hasHumanLockedCharter) {
+      const holder = truthCharter.judgment_authority_holder;
+      if (!holder || (typeof holder === 'string' && holder.trim() === '')) {
+        const msg = 'truth_charter.json: SAG has a current_highest source of type human_locked_charter, but TC.judgment_authority_holder is missing or empty; cross-file consistency requires both.';
+        if (strict) result.errors.push(msg);
+        else result.warnings.push(msg);
+      }
+    }
+  }
+
+  if (result.errors.length > 0) {
+    result.status = 'fail';
+  } else if (result.warnings.length > 0) {
+    result.status = 'warn';
+  } else {
+    result.status = 'pass';
+  }
+  return result;
+}
+
+module.exports = { runTcGate, VALID_TC_STATUS };