@aikdna/kdna-core 0.15.5 → 0.15.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v0.15.7 (2026-06-28)
+
+Story 6 — dependencies runtime. Supports semver-matching local/registry dependency resolution and topological sort-based loading order.
+
+- **Dependencies manifest schema support**: Explicitly declared `"dependencies"` as a first-class manifest property.
+- **Topological Sorting Resolver**: Added a robust, pure post-order DFS topological sorter with circular cycle, missing dependency, and version range mismatch checks.
+- **Topological Prompt Composition**: Enabled recursive, multi-domain prompt composition and flat topological JSON return inside `loadAuthorized`.
+
+
+## v0.15.6 (2026-06-28)
+
+Story 5 — Bundle payload type. Bumps KDNA manifest format schema to v2, introduces bundle-profile-v1 payload profile, and starts KDNA v1 format deprecation window.
+
+- **Bundle asset_type support:** added `"bundle"` to `asset_type` enum and `VALID_ASSET_TYPE` check.
+- **V2 Schema support:** bumped manifest schema version to v2.0, supporting `kdna_version` as `"2.0"`.
+- **Bundle profile support:** added `bundle-profile-v1` payload profile and validator.
+
+
 ## v0.15.5 (2026-06-28)
 
 Phase 12 audit follow-up. Closes 3 issues filed against this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.15.5",
+  "version": "0.15.7",
   "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
   "engines": {
     "node": ">=18.0.0"

package/schema/bundle-profile-v1.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aikdna/kdna/schema/bundle-profile-v1.schema.json",
+  "title": "Bundle Profile v1",
+  "description": "Schema for the payload entry of a KDNA bundle container.",
+  "type": "object",
+  "required": ["profile", "components"],
+  "additionalProperties": true,
+  "properties": {
+    "profile": {
+      "type": "string",
+      "const": "bundle-profile-v1",
+      "description": "Profile identifier. Must be the literal string 'bundle-profile-v1'."
+    },
+    "components": {
+      "type": "array",
+      "description": "List of component assets bundled in this container.",
+      "items": {
+        "type": "object",
+        "required": ["id", "path"],
+        "additionalProperties": true,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The unique identifier of the component asset."
+          },
+          "path": {
+            "type": "string",
+            "description": "Relative path to the component asset (.kdna container) within the bundle payload or bundle package."
+          },
+          "priority": {
+            "type": "integer",
+            "description": "Optional priority for resolving card conflicts."
+          }
+        }
+      }
+    }
+  }
+}

package/schema/manifest.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/aikdna/kdna/schema/manifest.schema.json",
-  "title": "KDNA Manifest v1",
+  "title": "KDNA Manifest v2",
   "description": "Schema for kdna.json, the public metadata layer of a .kdna container.",
   "type": "object",
   "required": [
@@ -23,7 +23,7 @@
     "kdna_version": {
       "type": "string",
       "description": "KDNA Core version this manifest conforms to.",
-      "const": "1.0"
+      "enum": ["1.0", "2.0"]
     },
     "asset_id": {
       "type": "string",
@@ -37,7 +37,7 @@
     },
     "asset_type": {
       "type": "string",
-      "enum": ["domain", "cluster", "tool", "sample", "fixture"],
+      "enum": ["domain", "cluster", "tool", "sample", "fixture", "bundle"],
       "description": "What kind of asset this is. Container format is the same; the value tells callers how to interpret the payload."
     },
     "title": {
@@ -92,7 +92,7 @@
         "profile": {
           "type": "string",
           "description": "Payload profile identifier (e.g. judgment-profile-v1).",
-          "const": "judgment-profile-v1"
+          "enum": ["judgment-profile-v1", "bundle-profile-v1"]
         }
       }
     },
@@ -195,6 +195,12 @@
         }
       }
     },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
     "encryption": { "type": "object" },
     "load_contract": { "$ref": "load-contract.schema.json" },
     "scope": { "type": "object" },

package/src/lint-pure.js

@@ -269,6 +269,7 @@ const VALID_ASSET_TYPE = new Set([
   'team_policy',
   'creator_style',
   'risk_guard',
+  'bundle',
 ]);
 
 const MANIFEST_REQUIRED = [

package/src/types.d.ts

@@ -504,6 +504,7 @@ export interface KDNAV1Checksums {
 }
 
 export function isV1SourceDir(inputPath: string): boolean;
+export function isV2SourceDir(inputPath: string): boolean;
 export function detectContainerFormat(inputPath: string): 'v1' | 'v2' | null;
 export function inspect(inputPath: string, options?: Record<string, any>): Record<string, any>;
 export function validate(inputPath: string, options?: Record<string, any>): Record<string, any>;

package/src/v1/index.js

@@ -125,6 +125,9 @@ function loadSchemas() {
   const payloadSchema = JSON.parse(
     fs.readFileSync(path.join(schemaDir, 'payload-profile-v1.schema.json'), 'utf8'),
   );
+  const bundlePayloadSchema = JSON.parse(
+    fs.readFileSync(path.join(schemaDir, 'bundle-profile-v1.schema.json'), 'utf8'),
+  );
   const checksumsSchema = JSON.parse(
     fs.readFileSync(path.join(schemaDir, 'checksums.schema.json'), 'utf8'),
   );
@@ -138,6 +141,7 @@ function loadSchemas() {
   _validators = {
     manifest: ajv.compile(manifestSchema),
     payload: ajv.compile(payloadSchema),
+    bundlePayload: ajv.compile(bundlePayloadSchema),
     checksums: ajv.compile(checksumsSchema),
   };
   return _validators;
@@ -159,6 +163,20 @@ function isV1SourceDir(absPath) {
   return mime === MIMETYPE_V1;
 }
 
+/**
+ * Detect whether a directory is a v2 source layout.
+ * Required entries: mimetype, kdna.json, payload.kdnab.
+ * mimetype content must equal "application/vnd.aikdna.kdna+zip".
+ */
+function isV2SourceDir(absPath) {
+  if (!fs.existsSync(absPath) || !fs.statSync(absPath).isDirectory()) return false;
+  for (const f of V1_REQUIRED_DIR_ENTRIES) {
+    if (!fs.existsSync(path.join(absPath, f))) return false;
+  }
+  const mime = fs.readFileSync(path.join(absPath, 'mimetype'), 'utf8');
+  return mime === MIMETYPE_V2;
+}
+
 /**
  * Detect whether a file is a v1 .kdna container.
  * Returns 'v1' | 'v2' | null. null = not a .kdna file or unreadable.
@@ -559,9 +577,9 @@ function readV1Layout(absPath) {
 
   // mimetype content must equal the literal v1 media type.
   const mime = map.mimetype.toString('utf8');
-  if (mime !== MIMETYPE_V1) {
+  if (mime !== MIMETYPE_V1 && mime !== MIMETYPE_V2) {
     throw new Error(
-      `not a KDNA v1 layout: mimetype is "${mime}", expected "${MIMETYPE_V1}"`,
+      `not a KDNA layout: mimetype is "${mime}", expected "${MIMETYPE_V1}" or "${MIMETYPE_V2}"`,
     );
   }
 
@@ -668,9 +686,12 @@ function runValidate(v1) {
       problems.push(`format: missing required entry ${f}`);
     }
   }
-  if (v1.map.mimetype && v1.map.mimetype.toString('utf8') !== MIMETYPE_V1) {
-    result.format_valid = false;
-    problems.push(`format: mimetype is not ${MIMETYPE_V1}`);
+  if (v1.map.mimetype) {
+    const mimeStr = v1.map.mimetype.toString('utf8');
+    if (mimeStr !== MIMETYPE_V1 && mimeStr !== MIMETYPE_V2) {
+      result.format_valid = false;
+      problems.push(`format: mimetype is not ${MIMETYPE_V1} or ${MIMETYPE_V2}`);
+    }
   }
 
   // schema gate — kdna.json against manifest.schema.json
@@ -717,11 +738,15 @@ function runValidate(v1) {
       problems.push('payload: encrypted envelope missing required fields (profile/ciphertext/key material)');
     }
     // Encrypted payload passes payload gate if envelope is structurally valid.
-  } else if (!validators.payload(payload)) {
+  } else {
     // Plaintext payload — full schema validation.
-    result.payload_valid = false;
-    for (const err of validators.payload.errors) {
-      problems.push(`payload: ${err.instancePath || '<root>'} ${err.message}`);
+    const isBundleProfile = v1.manifest.compatibility?.profile === 'bundle-profile-v1' || v1.manifest.asset_type === 'bundle';
+    const payloadValidator = isBundleProfile ? validators.bundlePayload : validators.payload;
+    if (!payloadValidator(payload)) {
+      result.payload_valid = false;
+      for (const err of payloadValidator.errors) {
+        problems.push(`payload: ${err.instancePath || '<root>'} ${err.message}`);
+      }
     }
   }
 
@@ -958,14 +983,15 @@ function unpack(inputPath, outputDir) {
   const entries = listZipEntries(absIn);
   // Sanity: v1 container must have mimetype as first entry with the v1 media type.
   if (entries.length === 0 || entries[0].name !== 'mimetype') {
-    throw new Error('not a KDNA v1 container: first entry is not mimetype');
+    throw new Error('not a KDNA container: first entry is not mimetype');
   }
   if (entries[0].method !== 0) {
-    throw new Error('not a KDNA v1 container: mimetype must be uncompressed');
+    throw new Error('not a KDNA container: mimetype must be uncompressed');
   }
-  if (entries[0].data.toString('utf8') !== MIMETYPE_V1) {
+  const mime = entries[0].data.toString('utf8');
+  if (mime !== MIMETYPE_V1 && mime !== MIMETYPE_V2) {
     throw new Error(
-      `not a KDNA v1 container: mimetype is "${entries[0].data.toString('utf8')}", expected "${MIMETYPE_V1}"`,
+      `not a KDNA container: mimetype is "${mime}", expected "${MIMETYPE_V1}" or "${MIMETYPE_V2}"`,
     );
   }
   const absOut = path.resolve(outputDir);
@@ -1128,6 +1154,17 @@ function canonicalToV1Layout(asset) {
     for (const [name, buf] of asset.entries) {
       map[name] = buf;
     }
+  } else {
+    map['mimetype'] = Buffer.from(asset.mimetype || '', 'utf8');
+    if (asset.manifest) {
+      map['kdna.json'] = Buffer.from(JSON.stringify(asset.manifest), 'utf8');
+    }
+    if (asset.payloadRaw) {
+      map['payload.kdnab'] = asset.payloadRaw;
+    }
+    if (asset.checksums) {
+      map['checksums.json'] = Buffer.from(JSON.stringify(asset.checksums), 'utf8');
+    }
   }
   return {
     kind: asset.sourceKind,
@@ -1204,6 +1241,46 @@ function planLoad(inputPath, opts = {}) {
   }
 
   const manifest = v1.manifest;
+
+  // Resolve dependencies if declared (Story 6)
+  const resolvedDeps = [];
+  if (manifest.dependencies && typeof manifest.dependencies === 'object' && Object.keys(manifest.dependencies).length > 0) {
+    if (typeof opts.resolveAsset === 'function') {
+      try {
+        const resolved = resolveDependencies(manifest, opts.resolveAsset);
+        resolvedDeps.push(...resolved);
+      } catch (err) {
+        plan.state = 'invalid';
+        plan.required_action = 'block';
+        plan.can_load_now = false;
+        plan.issues.push(buildLoadPlanIssue(
+          'KDNA_DEPENDENCY_RESOLUTION_FAILED',
+          'blocking',
+          err.message
+        ));
+        return finalizeLoadPlan(plan);
+      }
+    } else {
+      plan.state = 'invalid';
+      plan.required_action = 'block';
+      plan.can_load_now = false;
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_DEPENDENCY_RESOLVER_MISSING',
+        'blocking',
+        'Asset has dependencies but no dependency resolver callback was provided.'
+      ));
+      return finalizeLoadPlan(plan);
+    }
+  }
+
+  if (resolvedDeps.length > 0) {
+    plan.resolved_dependencies = resolvedDeps.map(dep => ({
+      name: dep.name,
+      version: dep.version,
+      path: dep.path
+    }));
+  }
+
   const payloadDeclaredEncrypted =
     manifest.payload && manifest.payload.encrypted === true;
   const encryptedEntries = Array.isArray(manifest.encryption && manifest.encryption.encrypted_entries)
@@ -1478,6 +1555,7 @@ module.exports = {
   MIMETYPE_V2,
   V1_REQUIRED_DIR_ENTRIES,
   isV1SourceDir,
+  isV2SourceDir,
   detectContainerFormat,
   readV1Layout,
   inspect,
@@ -1584,7 +1662,8 @@ function loadAuthorized(inputPath, opts = {}) {
     err.plan = plan;
     throw err;
   }
-  return loadV1Unsafe(inputPath, opts);
+  const mergedOpts = { ...opts, resolvedDependencies: plan.resolved_dependencies };
+  return loadV1Unsafe(inputPath, mergedOpts);
 }
 
 function loadV1(inputPath, opts = {}) {
@@ -1765,6 +1844,20 @@ function loadV1Unsafe(inputPath, opts = {}) {
     throw new Error(`unknown load profile: ${profile}`);
   }
 
+  if (opts.resolvedDependencies && opts.resolvedDependencies.length > 0) {
+    result.resolved_dependencies = opts.resolvedDependencies.map(dep => {
+      const depLoaded = loadV1Unsafe(dep.path, { ...opts, resolvedDependencies: [] });
+      return {
+        name: dep.name,
+        version: dep.version,
+        path: dep.path,
+        status: depLoaded.status,
+        profile: depLoaded.profile,
+        content: depLoaded.content
+      };
+    });
+  }
+
   if (as === 'prompt') {
     const c = result.content;
     if (!c || (c.scenarios && c.scenarios.length === 0 && !c.highest_question && !(c.axioms && c.axioms.length) && !(c.boundaries && c.boundaries.length))) {
@@ -1788,8 +1881,135 @@ function loadV1Unsafe(inputPath, opts = {}) {
     if (c.failure_modes && c.failure_modes.length) text += 'Failure modes:\n' + c.failure_modes.map((f) => '- ' + renderPromptItem(f)).join('\n') + '\n';
     if (c.patterns && c.patterns.length) text += 'Patterns:\n' + c.patterns.map((p) => '- ' + renderPromptItem(p)).join('\n') + '\n';
     if (c.note) text += 'Note: ' + c.note + '\n';
-    return { status: result.status, profile: result.profile, text: text.trim() };
+    
+    let textOut = text.trim();
+    if (opts.resolvedDependencies && opts.resolvedDependencies.length > 0) {
+      for (const dep of opts.resolvedDependencies) {
+        const depLoaded = loadV1Unsafe(dep.path, { ...opts, resolvedDependencies: [] });
+        if (depLoaded.text) {
+          textOut += '\n\n---\n\n' + depLoaded.text;
+        }
+      }
+    }
+    return { status: result.status, profile: result.profile, text: textOut };
   }
 
   return result;
 }
+
+// ─── Semver & Dependency Resolution (Story 6) ─────────────────────────
+
+function parseSemver(v) {
+  if (!v) return null;
+  const match = v.trim().match(/^v?([0-9]+)\.([0-9]+)\.([0-9]+)(?:-[a-zA-Z0-9.]+)?/);
+  if (!match) return null;
+  return {
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3], 10)
+  };
+}
+
+function compareSemver(v1, v2) {
+  const p1 = parseSemver(v1);
+  const p2 = parseSemver(v2);
+  if (!p1 || !p2) return 0;
+  if (p1.major !== p2.major) return p1.major - p2.major;
+  if (p1.minor !== p2.minor) return p1.minor - p2.minor;
+  return p1.patch - p2.patch;
+}
+
+function satisfies(version, range) {
+  if (!range || range === '*' || range.trim() === '') return true;
+  const r = range.trim();
+  
+  // Specific version comparison (e.g. "1.2.3")
+  if (/^[0-9]/.test(r)) {
+    return compareSemver(version, r) === 0;
+  }
+  
+  // ^ range comparison (e.g. "^1.2.3")
+  if (r.startsWith('^')) {
+    const min = r.slice(1);
+    const parsedMin = parseSemver(min);
+    if (!parsedMin) return false;
+    const parsedVer = parseSemver(version);
+    if (!parsedVer) return false;
+    // same major, and version >= min
+    if (parsedVer.major !== parsedMin.major) return false;
+    return compareSemver(version, min) >= 0;
+  }
+  
+  // ~ range comparison (e.g. "~1.2.3")
+  if (r.startsWith('~')) {
+    const min = r.slice(1);
+    const parsedMin = parseSemver(min);
+    if (!parsedMin) return false;
+    const parsedVer = parseSemver(version);
+    if (!parsedVer) return false;
+    // same major, same minor, and version >= min
+    if (parsedVer.major !== parsedMin.major || parsedVer.minor !== parsedMin.minor) return false;
+    return compareSemver(version, min) >= 0;
+  }
+  
+  // Custom ranges like ">=1.0.0 <2.0.0"
+  if (r.includes(' ')) {
+    const parts = r.split(/\s+/);
+    return parts.every(part => satisfies(version, part));
+  }
+  
+  if (r.startsWith('>=')) {
+    return compareSemver(version, r.slice(2)) >= 0;
+  }
+  if (r.startsWith('>')) {
+    return compareSemver(version, r.slice(1)) > 0;
+  }
+  if (r.startsWith('<=')) {
+    return compareSemver(version, r.slice(2)) <= 0;
+  }
+  if (r.startsWith('<')) {
+    return compareSemver(version, r.slice(1)) < 0;
+  }
+  
+  return false;
+}
+
+function resolveDependencies(manifest, resolveAssetCallback, seen = new Set(), stack = []) {
+  const resolved = [];
+  const deps = manifest.dependencies || {};
+  
+  for (const [name, range] of Object.entries(deps)) {
+    if (stack.includes(name)) {
+      throw new Error(`Circular dependency detected: ${stack.join(' -> ')} -> ${name}`);
+    }
+    
+    if (seen.has(name)) continue;
+    
+    // Resolve the dependency using the callback
+    const depAsset = resolveAssetCallback(name);
+    if (!depAsset) {
+      throw new Error(`Dependency not satisfied: "${name}" matching "${range}" is not installed.`);
+    }
+    
+    // Check if the resolved version satisfies the range
+    if (!satisfies(depAsset.version, range)) {
+      throw new Error(`Dependency mismatch: installed "${name}" version "${depAsset.version}" does not satisfy range "${range}".`);
+    }
+    
+    // Recurse
+    stack.push(name);
+    const subResolved = resolveDependencies(depAsset.manifest, resolveAssetCallback, seen, stack);
+    stack.pop();
+    
+    resolved.push(...subResolved);
+    resolved.push({
+      name,
+      version: depAsset.version,
+      path: depAsset.path,
+      manifest: depAsset.manifest
+    });
+    seen.add(name);
+  }
+  
+  return resolved;
+}

package/src/v1/index.mjs

@@ -5,6 +5,7 @@ export const MIMETYPE_V1 = v1.MIMETYPE_V1;
 export const MIMETYPE_V2 = v1.MIMETYPE_V2;
 export const V1_REQUIRED_DIR_ENTRIES = v1.V1_REQUIRED_DIR_ENTRIES;
 export const isV1SourceDir = v1.isV1SourceDir;
+export const isV2SourceDir = v1.isV2SourceDir;
 export const detectContainerFormat = v1.detectContainerFormat;
 export const readV1Layout = v1.readV1Layout;
 export const inspect = v1.inspect;