@aikdna/kdna-core 0.15.4 → 0.15.6

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 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
+repo (#145, #146, #147).
+
+- **#145** The `compilePatterns` output for `misunderstanding`
+  cards was already preserved (the v1 round-trip fix in 0.15.4
+  carried `failure_risk` / `applies_when` / `does_not_apply_when`).
+  The audit confirmed the fix is in place. No code change required;
+  this entry documents the verification.
+- **#146** `cardsFromV1Payload` (in the studio-cli consumer) now
+  infers a `type` for `payload.patterns` entries that omit it,
+  by inspecting the field set. Misunderstandings (which have
+  `wrong` + `correct`), terms (have `term` + `definition`),
+  banned terms, patterns, and aesthetics are now all picked up.
+  Truly unclassifiable entries are logged and skipped, never
+  silently dropped. The fix lives in the consumer
+  (`@aikdna/kdna-studio-cli` 0.8.6) rather than here.
+- **#147** `buildSigningPayload` now excludes `build-receipt.json`
+  and any entry under `reports/`, matching `buildContentDigest`.
+  The prior omission meant a producer that signed with this code
+  and a verifier that digested with `buildContentDigest` would
+  compute two different byte strings and the signature would fail
+  to verify. The exclusion set is now a single source of truth.
+  `docs/CANONICALIZATION.md` updated to spell out the rule and
+  warn producers/verifiers that any new exclusion MUST be added
+  to both paths in the same change.
+
 ## v0.15.4 (2026-06-28)
 
 Audit follow-ups (2026-06-28 round-trip verification). This release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.15.4",
+  "version": "0.15.6",
   "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"]
         }
       }
     },

package/src/asset-reader.js

@@ -235,9 +235,18 @@ function canonicalJsonEntry(entryName, entryBuf, options = {}) {
 }
 
 function buildSigningPayload(asset, options = {}) {
+  // Bug (#147): the prior version only excluded `.DS_Store` and
+  // `signature.json`, while `buildContentDigest` above also excludes
+  // `build-receipt.json` and any entry under `reports/`. A producer
+  // that signed with this code and a verifier that digested the
+  // asset with `buildContentDigest` would compute two different
+  // byte strings and the signature would fail to verify. The fix
+  // mirrors `buildContentDigest`'s exclusion set exactly.
   const parts = [];
   for (const entryName of [...asset.entries.keys()].sort()) {
     if (entryName === '.DS_Store' || entryName === 'signature.json') continue;
+    if (entryName === 'build-receipt.json') continue;
+    if (entryName.startsWith('reports/')) continue;
     const entryBuf = asset.readEntry(entryName);
     let payloadBuf = entryBuf;
     if (JSON_ENTRY_RE.test(entryName)) {

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,
@@ -1478,6 +1515,7 @@ module.exports = {
   MIMETYPE_V2,
   V1_REQUIRED_DIR_ENTRIES,
   isV1SourceDir,
+  isV2SourceDir,
   detectContainerFormat,
   readV1Layout,
   inspect,
@@ -1540,11 +1578,25 @@ function renderPromptItem(item) {
   if (item.term && item.why) return `${item.term}: ${item.why}`;
   if (item.wrong && item.correct) return `${item.wrong} -> ${item.correct}`;
   if (item.mode && item.correct) return `${item.mode} -> ${item.correct}`;
+  // Failure-mode entries from audit fixtures carry `mode` and `correct`
+  // but may be one-sided (only `mode`, only `correct`, only `why`).
+  // Fall through to a single-side render so the prompt never has
+  // `(unrendered card: ...)` for a card that has at least one
+  // populated judgment field. Bug (#61).
+  if (item.mode) return `failure mode: ${item.mode}`;
+  if (item.correct) return `correct: ${item.correct}`;
+  if (item.key_distinction) return item.key_distinction;
+  if (item.why) return `because: ${item.why}`;
   if (item.name && item.description) return `${item.name}: ${item.description}`;
   if (item.name) return item.name;
   if (item.one_sentence) return item.one_sentence;
   if (item.essence) return item.essence;
   if (item.question) return item.question;
+  // Self-check entries are sometimes stored as plain strings, sometimes
+  // as { question: "..." } objects, sometimes as { one_sentence: "..." }.
+  // The buildPayload path emits `one_sentence` for self_check, so
+  // try that before the last-resort fall-through. Bug (#61).
+  if (item.text) return item.text;
   // Last-resort fall-through. Returning the id (e.g. "bo_xxxx-...") makes
   // the output unreadable; prefer a note that the card is unrecognized.
   return `(unrendered card: ${item.type || 'unknown'})`;

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;