@aikdna/kdna-core 0.15.8 → 0.15.10

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+
+## v0.15.10 (2026-06-30)
+
+**API**: export `parseSemver`, `compareSemver`, `satisfies` from public module.
+
+These semver utilities were already used internally by kdna-core (Story 6 dependency
+resolution) but were not part of the public API. Exporting them allows consumers
+(e.g. `@aikdna/kdna-cli`) to use the canonical implementation rather than maintaining
+a parallel copy.
+
+- **`parseSemver(v)`** — parse a semver string into `{major, minor, patch}` or `null`
+- **`compareSemver(a, b)`** — compare two version strings, returns `< 0 | 0 | > 0`
+- **`satisfies(version, range)`** — test a version against a range (`^`, `~`, `>=`, etc.)
+
+No breaking changes. Purely additive.
+
+## v0.15.9 (2026-06-28)
+
+Story 12 — Asset inheritance (`extends` field, RFC #148 v2.x Phase 3).
+
+- **`extends` field in `manifest.schema.json`**: assets may declare
+  `extends: "@scope/name@^1.0.0"` (string) or `extends: { name, version }`
+  (object). Distinct from `dependencies` (peer composition): `extends`
+  creates a single-inheritance hierarchy where the child specialises the parent.
+- **`planLoad` extends resolution**: when a `resolveAsset` callback is provided
+  and the manifest declares `extends`, `planLoad` resolves the base asset and
+  records `extends_chain` in the plan output. Non-blocking — missing base
+  emits a WARNING issue, not a blocking error.
+- **`loadAuthorized` passes `extends_chain`** from the plan to `loadV1Unsafe`
+  so the inheritance merge is applied at load time.
+- **`loadV1Unsafe` inheritance merge**: when `extendsChain` is non-empty, the
+  base asset's content is loaded and merged with the child's content. Merge
+  rules: child axioms override parent axioms with the same `id`; parent axioms
+  not in child are inherited; same for boundaries (by `scope` text);
+  `highest_question` falls back to parent if child omits it. Non-blocking.
+- **`result.extends_chain`** and **`result.inheritance_applied`** fields added
+  to load output when inheritance is applied.
+- Blocks Story 13 (trust levels) per Section 6 sequencing.
+
 ## v0.15.8 (2026-06-28)
 
 Story 11 — RAG namespace isolation (RFC #148 v2.x Phase 3).

package/package.json

@@ -1,70 +1,70 @@
 {
-  "name": "@aikdna/kdna-core",
-  "version": "0.15.8",
-  "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "type": "commonjs",
-  "main": "src/index.js",
-  "module": "src/index.mjs",
-  "exports": {
-    ".": {
-      "import": "./src/index.mjs",
-      "require": "./src/index.js",
-      "types": "./src/types.d.ts"
+    "name": "@aikdna/kdna-core",
+    "version": "0.15.10",
+    "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
+    "engines": {
+        "node": ">=18.0.0"
     },
-    "./package.json": "./package.json",
-    "./schema/*": "./schema/*",
-    "./v1": {
-      "import": "./src/v1/index.mjs",
-      "require": "./src/v1/index.js",
-      "types": "./src/types.d.ts"
-    }
-  },
-  "types": "src/types.d.ts",
-  "scripts": {
-    "test": "node ../../scripts/run-node-tests.js test/*.test.js && node -e \"const m = require('./src/index.js'); console.log('kdna-core exports:', Object.keys(m).join(', '));\"",
-    "prepublishOnly": "npm run release:check",
-    "release:check": "node scripts/check-release-readiness.js"
-  },
-  "files": [
-    "src/",
-    "schema/",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE",
-    "NOTICE"
-  ],
-  "keywords": [
-    "kdna",
-    "kdna-core",
-    "ai-agent",
-    "judgment-assets"
-  ],
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aikdna/kdna.git",
-    "directory": "packages/kdna-core"
-  },
-  "homepage": "https://aikdna.com",
-  "peerDependencies": {
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1"
-  },
-  "peerDependenciesMeta": {
-    "ajv": {
-      "optional": true
+    "type": "commonjs",
+    "main": "src/index.js",
+    "module": "src/index.mjs",
+    "exports": {
+        ".": {
+            "import": "./src/index.mjs",
+            "require": "./src/index.js",
+            "types": "./src/types.d.ts"
+        },
+        "./package.json": "./package.json",
+        "./schema/*": "./schema/*",
+        "./v1": {
+            "import": "./src/v1/index.mjs",
+            "require": "./src/v1/index.js",
+            "types": "./src/types.d.ts"
+        }
+    },
+    "types": "src/types.d.ts",
+    "scripts": {
+        "test": "node ../../scripts/run-node-tests.js test/*.test.js && node -e \"const m = require('./src/index.js'); console.log('kdna-core exports:', Object.keys(m).join(', '));\"",
+        "prepublishOnly": "npm run release:check",
+        "release:check": "node scripts/check-release-readiness.js"
+    },
+    "files": [
+        "src/",
+        "schema/",
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE",
+        "NOTICE"
+    ],
+    "keywords": [
+        "kdna",
+        "kdna-core",
+        "ai-agent",
+        "judgment-assets"
+    ],
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/aikdna/kdna.git",
+        "directory": "packages/kdna-core"
+    },
+    "homepage": "https://aikdna.com",
+    "peerDependencies": {
+        "ajv": "^8.17.1",
+        "ajv-formats": "^3.0.1"
+    },
+    "peerDependenciesMeta": {
+        "ajv": {
+            "optional": true
+        },
+        "ajv-formats": {
+            "optional": true
+        }
     },
-    "ajv-formats": {
-      "optional": true
+    "dependencies": {
+        "@noble/hashes": "^1.8.0",
+        "cbor-x": "^1.6.4",
+        "ajv": "^8.20.0",
+        "ajv-formats": "^3.0.1"
     }
-  },
-  "dependencies": {
-    "@noble/hashes": "^1.8.0",
-    "cbor-x": "^1.6.4",
-    "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1"
-  }
 }

package/schema/manifest.schema.json

@@ -201,6 +201,24 @@
         "type": "string"
       }
     },
+    "extends": {
+      "description": "Asset inheritance declaration (Story 12). This asset inherits judgment content from the named base asset. Distinct from 'dependencies' (peer composition): 'extends' creates a single-inheritance hierarchy where the child specialises the parent. The child's cards override the parent's cards with the same ID; parent cards not overridden are inherited. Format: '@scope/name@semver-range' string, or an object with 'name' and optional 'version' fields.",
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Scoped asset name with optional version, e.g. '@aikdna/sales@^1.0.0'."
+        },
+        {
+          "type": "object",
+          "required": ["name"],
+          "additionalProperties": false,
+          "properties": {
+            "name":    { "type": "string", "description": "Scoped asset name, e.g. '@aikdna/sales'." },
+            "version": { "type": "string", "description": "Semver range, e.g. '^1.0.0'. Defaults to '*' if absent." }
+          }
+        }
+      ]
+    },
     "encryption": { "type": "object" },
     "load_contract": { "$ref": "load-contract.schema.json" },
     "scope": { "type": "object" },

package/src/asset-reader.js

@@ -311,28 +311,42 @@ function verifyHumanLockSignatures(coreData, manifest, errors, warnings) {
     // Skip if no public key available (unsigned assets are valid)
     return;
   }
-  const axioms = coreData?.axioms || [];
-  if (!Array.isArray(axioms) || axioms.length === 0) return;
+
+  // All card-type arrays in KDNA_Core.json that may carry human_lock.
+  // Ordered by how they appear in the compiled payload (compileCore in
+  // kdna-studio-core/src/compile/index.js).
+  const CORE_CARD_ARRAYS = [
+    ['axioms', 'axiom'],
+    ['ontology', 'ontology'],
+    ['frameworks', 'framework'],
+    ['boundaries', 'boundary'],
+    ['risks', 'risk'],
+    ['stances', 'stance'],
+  ];
 
   let verified = 0, missing = 0, invalid = 0;
-  for (const ax of axioms) {
-    const hl = ax.human_lock;
-    if (!hl || !hl.signature) {
-      // Only warn for locked cards without signature
-      if (ax.status === 'locked' || ax.status === 'tested' || ax.status === 'published') {
-        missing++;
+  for (const [arrayName, _cardType] of CORE_CARD_ARRAYS) {
+    const cards = coreData?.[arrayName];
+    if (!Array.isArray(cards) || cards.length === 0) continue;
+
+    for (const card of cards) {
+      const hl = card.human_lock;
+      if (!hl || !hl.signature) {
+        if (card.status === 'locked' || card.status === 'tested' || card.status === 'published') {
+          missing++;
+        }
+        continue;
+      }
+      try {
+        const payload = [card.id, hl.statement || '', hl.judgment_fingerprint || ''].join('\n');
+        const sig = Buffer.from(String(hl.signature).replace(/^ed25519:/, ''), 'hex');
+        const key = crypto.createPublicKey(publicKeyPEM);
+        const ok = crypto.verify(null, Buffer.from(payload), key, sig);
+        if (ok) { verified++; }
+        else { invalid++; }
+      } catch {
+        invalid++;
       }
-      continue;
-    }
-    try {
-      const payload = [ax.id, hl.statement || '', hl.judgment_fingerprint || ''].join('\n');
-      const sig = Buffer.from(String(hl.signature).replace(/^ed25519:/, ''), 'hex');
-      const key = crypto.createPublicKey(publicKeyPEM);
-      const ok = crypto.verify(null, Buffer.from(payload), key, sig);
-      if (ok) { verified++; }
-      else { invalid++; }
-    } catch {
-      invalid++;
     }
   }
 

package/src/v1/index.js

@@ -1273,6 +1273,55 @@ function planLoad(inputPath, opts = {}) {
     }
   }
 
+  // Resolve extends chain if declared (Story 12)
+  // 'extends' is single-inheritance: child overrides parent's cards with same ID.
+  // Distinct from 'dependencies' (peer composition).
+  if (manifest.extends) {
+    const extendsDecl = manifest.extends;
+    const extendsName = typeof extendsDecl === 'string'
+      ? extendsDecl.replace(/@[^@]+$/, '') || extendsDecl  // strip @version for resolver key
+      : extendsDecl.name;
+    const extendsVersion = typeof extendsDecl === 'string'
+      ? (extendsDecl.match(/@([^@]+)$/) || [])[1] || '*'
+      : (extendsDecl.version || '*');
+
+    if (typeof opts.resolveAsset === 'function') {
+      try {
+        const baseAsset = opts.resolveAsset(extendsName);
+        if (!baseAsset) {
+          plan.issues.push(buildLoadPlanIssue(
+            'KDNA_EXTENDS_NOT_FOUND',
+            'warning',
+            `Base asset "${extendsName}" declared in 'extends' could not be resolved. Inheritance chain incomplete.`
+          ));
+        } else if (baseAsset.manifest && !satisfies(baseAsset.version, extendsVersion)) {
+          plan.issues.push(buildLoadPlanIssue(
+            'KDNA_EXTENDS_VERSION_MISMATCH',
+            'warning',
+            `Base asset "${extendsName}@${baseAsset.version}" does not satisfy extends range "${extendsVersion}".`
+          ));
+        } else if (baseAsset.path) {
+          plan.extends_chain = [
+            { name: extendsName, version: baseAsset.version || extendsVersion, path: baseAsset.path },
+          ];
+        }
+      } catch (err) {
+        plan.issues.push(buildLoadPlanIssue(
+          'KDNA_EXTENDS_RESOLUTION_FAILED',
+          'warning',
+          `extends resolution failed: ${err.message}`
+        ));
+      }
+    } else {
+      // No resolver: extends chain unresolvable — warn, don't block
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_EXTENDS_RESOLVER_MISSING',
+        'warning',
+        `Asset declares 'extends: ${JSON.stringify(manifest.extends)}' but no resolver was provided. Inheritance chain will not be applied.`
+      ));
+    }
+  }
+
   if (resolvedDeps.length > 0) {
     plan.resolved_dependencies = resolvedDeps.map(dep => ({
       name: dep.name,
@@ -1567,6 +1616,12 @@ module.exports = {
   unpack,
   loadV1,
   FORBIDDEN_OUTPUT_TERMS,
+  // Semver utilities (Story 6 / Story 13) — exported so consumers
+  // (e.g. kdna-cli) can use the canonical implementation instead of
+  // duplicating it.
+  parseSemver,
+  compareSemver,
+  satisfies,
 };
 
 // ─── loadV1 — v1 runtime loading / load contract ──────────────────────
@@ -1662,7 +1717,12 @@ function loadAuthorized(inputPath, opts = {}) {
     err.plan = plan;
     throw err;
   }
-  const mergedOpts = { ...opts, resolvedDependencies: plan.resolved_dependencies };
+  const mergedOpts = {
+    ...opts,
+    resolvedDependencies: plan.resolved_dependencies,
+    // Pass extends_chain from plan to loadV1Unsafe so inheritance is applied (Story 12)
+    extendsChain: plan.extends_chain || [],
+  };
   return loadV1Unsafe(inputPath, mergedOpts);
 }
 
@@ -1844,6 +1904,54 @@ function loadV1Unsafe(inputPath, opts = {}) {
     throw new Error(`unknown load profile: ${profile}`);
   }
 
+  // Asset inheritance (Story 12): if the manifest declares 'extends' and
+  // the plan resolved an extends_chain, load the base asset and merge its
+  // content with the child's content. Child cards with the same ID override
+  // the parent's; parent cards not overridden are inherited.
+  if (opts.extendsChain && opts.extendsChain.length > 0 && result.content) {
+    try {
+      const base = opts.extendsChain[0];
+      const baseLoaded = loadV1Unsafe(base.path, {
+        ...opts,
+        resolvedDependencies: [],
+        extendsChain: [],
+      });
+      if (baseLoaded && baseLoaded.content) {
+        const bc = baseLoaded.content;
+        const cc = result.content;
+        // Merge axioms: child overrides by id; parent axioms not in child are added
+        if (bc.axioms || cc.axioms) {
+          const childIds = new Set((cc.axioms || []).map((a) => a.id).filter(Boolean));
+          const inheritedAxioms = (bc.axioms || []).filter((a) => a.id && !childIds.has(a.id));
+          cc.axioms = [...inheritedAxioms, ...(cc.axioms || [])];
+        }
+        // Merge boundaries: child overrides by scope text; parent not overridden are inherited
+        if (bc.boundaries || cc.boundaries) {
+          const childScopes = new Set(
+            (cc.boundaries || []).map((b) => (b.scope || '').toLowerCase().trim()),
+          );
+          const inheritedBoundaries = (bc.boundaries || []).filter(
+            (b) => !childScopes.has((b.scope || '').toLowerCase().trim()),
+          );
+          cc.boundaries = [...inheritedBoundaries, ...(cc.boundaries || [])];
+        }
+        // Inherit highest_question from parent if child doesn't declare one
+        if (!cc.highest_question && bc.highest_question) {
+          cc.highest_question = bc.highest_question;
+        }
+        result.extends_chain = opts.extendsChain.map((e) => ({
+          name: e.name,
+          version: e.version,
+          path: e.path,
+        }));
+        result.inheritance_applied = true;
+      }
+    } catch (_) {
+      // extends merge is best-effort — never block load
+      result.inheritance_applied = false;
+    }
+  }
+
    if (opts.resolvedDependencies && opts.resolvedDependencies.length > 0) {
     result.resolved_dependencies = opts.resolvedDependencies.map(dep => {
       const depLoaded = loadV1Unsafe(dep.path, { ...opts, resolvedDependencies: [] });
@@ -1901,7 +2009,7 @@ function loadV1Unsafe(inputPath, opts = {}) {
     if (c.note) text += 'Note: ' + c.note + '\n';
     
     let textOut = text.trim();
-    if (opts.resolvedDependencies && opts.resolvedDependencies.length > 0) {
+   if (opts.resolvedDependencies && opts.resolvedDependencies.length > 0) {
       for (const dep of opts.resolvedDependencies) {
         const depLoaded = loadV1Unsafe(dep.path, { ...opts, resolvedDependencies: [] });
         if (depLoaded.text) {