@aikdna/kdna-core 0.15.11 → 0.16.0

package/src/v1/index.js

@@ -1,17 +1,15 @@
 /**
- * v1-cli.js — KDNA Core v1 inspect / validate / pack / unpack for the
- * kdna monorepo CLI shim.
+ * KDNA Asset Container inspect / validate / pack / unpack implementation.
  *
  * KDNA Core is the official KDNA judgment-asset format and runtime
  * loading contract. .kdna assets are created, inspected, packed,
  * unpacked, and validated through the official KDNA toolchain. This
- * module is the v1 component of that toolchain.
  *
- * The KDNA Core v1 file format is documented in docs/core/file-format.md.
+ * The KDNA Asset Container is documented in docs/core/file-format.md.
  * This module is the shared implementation that:
  *
- *   - packages/kdna/bin/kdna.js uses as a v1-aware router
- *   - scripts/v1-*.mjs delegate to (via child_process) so the legacy
+ *   - packages/kdna/bin/kdna.js uses as its container router
+ *   - compatibility scripts delegate to it so historical tooling
  *     scripts and the official CLI cannot drift
  *
  * Hard rules from the format spec:
@@ -38,24 +36,29 @@ const fs = require('node:fs');
 const path = require('node:path');
 const zlib = require('node:zlib');
 const crypto = require('node:crypto');
+const cbor = require('cbor-x');
+const {
+  EXTERNAL_ENVELOPE_PROFILE,
+  validateExternalEnvelope,
+  isVerifiedExternalEntitlement,
+} = require('../external-key-grant');
 
 const { readAsset } = (() => {
   try {
     return require('../container-dispatcher.js');
   } catch {
-    return { readAsset: null, MIMETYPE_V1: null, MIMETYPE_V2: null };
+    return { readAsset: null };
   }
 })();
 
-const MIMETYPE_V1 = 'application/vnd.kdna.asset';
-const MIMETYPE_V2 = 'application/vnd.aikdna.kdna+zip';
-const V1_REQUIRED_DIR_ENTRIES = ['mimetype', 'kdna.json', 'payload.kdnab'];
-const V1_OPTIONAL_DIR_ENTRIES = ['checksums.json', 'signatures', 'attachments'];
-const V1_ALLOWED_TOP_LEVEL_ENTRIES = new Set([
-  ...V1_REQUIRED_DIR_ENTRIES,
-  ...V1_OPTIONAL_DIR_ENTRIES,
+const MIMETYPE = 'application/vnd.kdna.asset';
+const REQUIRED_DIR_ENTRIES = ['mimetype', 'kdna.json', 'payload.kdnab'];
+const OPTIONAL_DIR_ENTRIES = ['checksums.json', 'signatures', 'attachments'];
+const ALLOWED_TOP_LEVEL_ENTRIES = new Set([
+  ...REQUIRED_DIR_ENTRIES,
+  ...OPTIONAL_DIR_ENTRIES,
 ]);
-const V1_FORBIDDEN_LEGACY_TOP_LEVEL = new Set([
+const FORBIDDEN_LEGACY_TOP_LEVEL = new Set([
   'KDNA_Core.json',
   'KDNA_Patterns.json',
   'KDNA_Scenarios.json',
@@ -64,6 +67,12 @@ const V1_FORBIDDEN_LEGACY_TOP_LEVEL = new Set([
   'KDNA_Evolution.json',
 ]);
 
+// Legacy aliases — prefer the unversioned names above
+const V1_REQUIRED_DIR_ENTRIES = REQUIRED_DIR_ENTRIES;
+const V1_OPTIONAL_DIR_ENTRIES = OPTIONAL_DIR_ENTRIES;
+const V1_ALLOWED_TOP_LEVEL_ENTRIES = ALLOWED_TOP_LEVEL_ENTRIES;
+const V1_FORBIDDEN_LEGACY_TOP_LEVEL = FORBIDDEN_LEGACY_TOP_LEVEL;
+
 const DEFAULT_CONTAINER_LIMITS = Object.freeze({
   maxContainerBytes: 25 * 1024 * 1024,
   maxEntries: 128,
@@ -172,49 +181,32 @@ function loadSchemas() {
 // ─── Format detection ──────────────────────────────────────────────────
 
 /**
- * Detect whether a directory is a v1 source layout.
+ * Detect whether a directory is a KDNA authoring source layout.
  * Required entries: mimetype, kdna.json, payload.kdnab.
  * mimetype content must equal "application/vnd.kdna.asset".
  */
-function isV1SourceDir(absPath) {
+function isKdnaSourceDir(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_V1;
+  return mime === MIMETYPE;
 }
 
 /**
- * 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.
+ * Detect whether a file is a .kdna container.
+ * Returns 'kdna' | null. null = not a .kdna file or unreadable.
  */
 function detectContainerFormat(absPath) {
   if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) return null;
-  // Quick header check: must look like a ZIP.
   const fd = fs.openSync(absPath, 'r');
   const head = Buffer.alloc(4);
   fs.readSync(fd, head, 0, 4, 0);
   fs.closeSync(fd);
   if (head[0] !== 0x50 || head[1] !== 0x4b) return null;
 
-  // Read only the first central-directory entry. Dangerous later entries
-  // must not make detection fall through to a less strict legacy route;
-  // readV1Layout/validate will reject them with the secure container reader.
   let first;
   try {
     first = readFirstZipEntry(absPath);
@@ -222,12 +214,9 @@ function detectContainerFormat(absPath) {
     return null;
   }
   if (first.name !== 'mimetype') return null;
-  // The mimetype entry must be STORED (method 0).
   if (first.method !== 0) return null;
   const mime = first.method === 0 ? first.data.toString('utf8') : '';
-  if (mime === MIMETYPE_V1) return 'v1';
-  if (mime === MIMETYPE_V2) return 'v2';
-  return null;
+  return (mime === MIMETYPE) ? 'kdna' : null;
 }
 
 // ─── ZIP I/O ────────────────────────────────────────────────────────────
@@ -550,10 +539,10 @@ function readV1Layout(absPath) {
     for (const f of V1_REQUIRED_DIR_ENTRIES) {
       const full = path.join(absPath, f);
       if (!fs.existsSync(full)) {
-        throw new Error(`not a KDNA v1 source dir: missing ${f}`);
+        throw new Error(`not a KDNA authoring source directory: missing ${f}`);
       }
       if (fs.lstatSync(full).isSymbolicLink()) {
-        throw new Error(`not a KDNA v1 source dir: ${f} must not be a symlink`);
+        throw new Error(`not a KDNA authoring source directory: ${f} must not be a symlink`);
       }
     }
     for (const f of [...V1_REQUIRED_DIR_ENTRIES, ...V1_OPTIONAL_DIR_ENTRIES]) {
@@ -571,10 +560,10 @@ function readV1Layout(absPath) {
     kind = 'file';
     entries = listZipEntries(absPath);
     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 Asset 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 Asset Container: mimetype must be uncompressed');
     }
     for (const e of entries) {
       // We only need the well-known entries; signatures/ attachments/ etc.
@@ -590,7 +579,7 @@ function readV1Layout(absPath) {
     }
     for (const f of V1_REQUIRED_DIR_ENTRIES) {
       if (!map[f]) {
-        throw new Error(`not a KDNA v1 container: missing ${f}`);
+        throw new Error(`not a KDNA Asset Container: missing ${f}`);
       }
     }
   } else {
@@ -599,9 +588,9 @@ function readV1Layout(absPath) {
 
   // mimetype content must equal the literal v1 media type.
   const mime = map.mimetype.toString('utf8');
-  if (mime !== MIMETYPE_V1 && mime !== MIMETYPE_V2) {
+  if (mime !== MIMETYPE) {
     throw new Error(
-      `not a KDNA layout: mimetype is "${mime}", expected "${MIMETYPE_V1}" or "${MIMETYPE_V2}"`,
+      `not a KDNA layout: mimetype is "${mime}", expected "${MIMETYPE}"`,
     );
   }
 
@@ -657,6 +646,24 @@ function assertJsonWithinLimits(value, name, limits) {
   walk(value, 0);
 }
 
+function parsePayloadEntry(name, bytes, opts = {}) {
+  if (!Buffer.isBuffer(bytes)) {
+    throw new Error(`${name} is not a file entry`);
+  }
+  const limits = { ...DEFAULT_CONTAINER_LIMITS, ...(opts.limits || {}) };
+  if (bytes.length > limits.maxEntryBytes) {
+    throw new Error(`${name} exceeds maximum size (${limits.maxEntryBytes} bytes)`);
+  }
+  let parsed;
+  try {
+    parsed = cbor.decode(bytes);
+  } catch {
+    throw new Error(`${name}: not valid CBOR. payload.kdnab must be CBOR-encoded (kdna_version 1.0).`);
+  }
+  assertJsonWithinLimits(parsed, name, limits);
+  return parsed;
+}
+
 // ─── inspect ───────────────────────────────────────────────────────────
 
 /**
@@ -710,9 +717,9 @@ function runValidate(v1) {
   }
   if (v1.map.mimetype) {
     const mimeStr = v1.map.mimetype.toString('utf8');
-    if (mimeStr !== MIMETYPE_V1 && mimeStr !== MIMETYPE_V2) {
+    if (mimeStr !== MIMETYPE) {
       result.format_valid = false;
-      problems.push(`format: mimetype is not ${MIMETYPE_V1} or ${MIMETYPE_V2}`);
+      problems.push(`format: mimetype is not ${MIMETYPE}`);
     }
   }
 
@@ -721,7 +728,7 @@ function runValidate(v1) {
   if (!validators) {
     result.schema_valid = false;
     problems.push(
-      'schema: ajv not available. KDNA Core v1 requires ajv and ajv-formats for JSON-Schema validation. Run: npm install ajv ajv-formats (or: npm install -g ajv ajv-formats for global CLI users)',
+      'schema: KDNA Core requires ajv and ajv-formats for JSON-Schema validation. Run: npm install ajv ajv-formats (or: npm install -g ajv ajv-formats for global CLI users)',
     );
     return finalizeValidate(result, problems);
   }
@@ -736,10 +743,10 @@ function runValidate(v1) {
   // For actually encrypted payloads (envelopes), skip schema validation.
   let payload;
   try {
-    payload = parseJsonEntry('payload.kdnab', v1.map['payload.kdnab']);
+    payload = parsePayloadEntry("payload.kdnab", v1.map['payload.kdnab']);
   } catch (e) {
     result.payload_valid = false;
-    problems.push(`payload: not valid JSON (${e.message})`);
+    problems.push(`payload: not valid KDNA payload (${e.message})`);
     return finalizeValidate(result, problems);
   }
 
@@ -754,7 +761,16 @@ function runValidate(v1) {
       result.payload_valid = false;
       problems.push(`payload: encrypted envelope profile ${payload.profile || 'unknown'} does not match manifest encryption profile ${encProfile}`);
     }
-    const hasKeyMaterial = !!payload.wrapped_key || (Array.isArray(payload.key_slots) && payload.key_slots.length > 0);
+    let hasKeyMaterial = !!payload.wrapped_key || (Array.isArray(payload.key_slots) && payload.key_slots.length > 0);
+    if (payload.profile === EXTERNAL_ENVELOPE_PROFILE) {
+      try {
+        validateExternalEnvelope(payload);
+        hasKeyMaterial = true;
+      } catch (error) {
+        result.payload_valid = false;
+        problems.push(`payload: ${error.message}`);
+      }
+    }
     if (!payload.profile || !payload.ciphertext || !hasKeyMaterial) {
       result.payload_valid = false;
       problems.push('payload: encrypted envelope missing required fields (profile/ciphertext/key material)');
@@ -915,7 +931,7 @@ function buildChecksumsV1(sourceDir) {
 // ─── pack ──────────────────────────────────────────────────────────────
 
 /**
- * Pack a v1 source directory into a .kdna container. Output is
+ * Pack an authoring source directory into a .kdna asset. Output is
  * deterministic: the same source directory packed twice produces
  * byte-identical output (fixed DOS timestamps, fixed entry order,
  * mimetype first).
@@ -931,12 +947,22 @@ function pack(sourceDir, outputPath) {
     }
   }
   const mime = fs.readFileSync(path.join(absSrc, 'mimetype'), 'utf8');
-  if (mime !== MIMETYPE_V1) {
-    throw new Error(`cannot pack: mimetype is "${mime}", expected "${MIMETYPE_V1}"`);
+  if (mime !== MIMETYPE) {
+    throw new Error(`cannot pack: mimetype is "${mime}", expected "${MIMETYPE}"`);
   }
 
   // Collect deterministically; mimetype is forced first.
   const collected = listSourceDir(absSrc);
+  for (const entry of collected) {
+    const normalizedName = normalizeContainerEntryName(entry.rel);
+    const topLevel = normalizedName.split('/')[0];
+    if (!ALLOWED_TOP_LEVEL_ENTRIES.has(topLevel)) {
+      if (FORBIDDEN_LEGACY_TOP_LEVEL.has(topLevel)) {
+        throw new Error(`cannot pack forbidden top-level source entry: ${topLevel}`);
+      }
+      throw new Error(`cannot pack unsupported top-level entry: ${topLevel}`);
+    }
+  }
   const order = ['mimetype', ...collected.map((e) => e.rel).filter((n) => n !== 'mimetype')];
 
   // Build the ZIP body.
@@ -946,7 +972,7 @@ function pack(sourceDir, outputPath) {
   for (const rel of order) {
     let data;
     if (rel === 'mimetype') {
-      data = Buffer.from(MIMETYPE_V1, 'utf8');
+      data = Buffer.from(MIMETYPE, 'utf8');
     } else {
       const found = collected.find((e) => e.rel === rel);
       if (!found) continue;
@@ -1003,7 +1029,7 @@ function unpack(inputPath, outputDir) {
     throw new Error(`not a file: ${absIn}`);
   }
   const entries = listZipEntries(absIn);
-  // Sanity: v1 container must have mimetype as first entry with the v1 media type.
+  // Sanity: the asset must have mimetype as its first, uncompressed entry.
   if (entries.length === 0 || entries[0].name !== 'mimetype') {
     throw new Error('not a KDNA container: first entry is not mimetype');
   }
@@ -1011,9 +1037,9 @@ function unpack(inputPath, outputDir) {
     throw new Error('not a KDNA container: mimetype must be uncompressed');
   }
   const mime = entries[0].data.toString('utf8');
-  if (mime !== MIMETYPE_V1 && mime !== MIMETYPE_V2) {
+  if (mime !== MIMETYPE) {
     throw new Error(
-      `not a KDNA container: mimetype is "${mime}", expected "${MIMETYPE_V1}" or "${MIMETYPE_V2}"`,
+      `not a KDNA container: mimetype is "${mime}", expected "${MIMETYPE}"`,
     );
   }
   const absOut = path.resolve(outputDir);
@@ -1087,12 +1113,11 @@ function finalizeLoadPlan(plan) {
   return plan;
 }
 
-function computeSourceFingerprint(inputPath, v1) {
-  const absPath = path.resolve(inputPath);
-  if (v1.kind === 'file') {
-    return `sha256:${crypto.createHash('sha256').update(fs.readFileSync(absPath)).digest('hex')}`;
-  }
-
+function computeSourceFingerprint(_inputPath, v1) {
+  // Fingerprint the logical entries, not the transport ZIP bytes. DEFLATE
+  // output can differ between zlib versions and operating systems even when
+  // every uncompressed KDNA entry is identical. LoadPlan conformance must be
+  // stable across JS, Swift, CI runners, and repackaging transports.
   const hash = crypto.createHash('sha256');
   for (const name of Object.keys(v1.map).sort()) {
     const bytes = v1.map[name];
@@ -1197,14 +1222,15 @@ function canonicalToV1Layout(asset) {
 }
 
 /**
- * Plan a KDNA v1 runtime load without decrypting or emitting judgment content.
+ * Plan a KDNA runtime load without decrypting or emitting judgment content.
  * Product consumers such as Chat should render authorization UI from this
  * result instead of parsing manifest fields directly.
  */
 function planLoad(inputPath, opts = {}) {
   let v1;
 
-  // Try the unified container dispatcher first (handles v1 dirs, v1 containers, v2 containers)
+  // Try the unified container dispatcher first; the internal compatibility
+  // reader below remains available only for authoring and migration tooling.
   if (readAsset !== null) {
     try {
       const asset = readAsset(path.resolve(inputPath));
@@ -1264,6 +1290,36 @@ function planLoad(inputPath, opts = {}) {
 
   const manifest = v1.manifest;
 
+  function externalEntitlementMatchesCurrentAsset(entitlement) {
+    if (!isVerifiedExternalEntitlement(entitlement) || !entitlement.asset) return false;
+    let checksums;
+    try {
+      checksums = v1.map['checksums.json']
+        ? parseJsonEntry('checksums.json', v1.map['checksums.json'])
+        : null;
+    } catch {
+      return false;
+    }
+    return entitlement.asset.asset_id === (manifest.asset_id || manifest.name)
+      && entitlement.asset.asset_uid === manifest.asset_uid
+      && entitlement.asset.version === manifest.version
+      && entitlement.asset.digest === checksums?.asset_digest
+      && entitlement.asset.entry_path === manifest.payload?.path;
+  }
+
+  function rejectExternalEntitlementMismatch() {
+    plan.state = 'invalid';
+    plan.required_action = 'block';
+    plan.can_load_now = false;
+    plan.projection_policy = 'none';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_GRANT_ASSET_MISMATCH',
+      'blocking',
+      'The verified account/device grant is bound to a different asset, version, digest, or encrypted entry.',
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
   // Resolve dependencies if declared (Story 6)
   const resolvedDeps = [];
   if (manifest.dependencies && typeof manifest.dependencies === 'object' && Object.keys(manifest.dependencies).length > 0) {
@@ -1435,6 +1491,23 @@ function planLoad(inputPath, opts = {}) {
     }
 
     if (plan.entitlement_profile === 'account') {
+      if (isVerifiedExternalEntitlement(opts.entitlement)) {
+        if (!externalEntitlementMatchesCurrentAsset(opts.entitlement)) {
+          return rejectExternalEntitlementMismatch();
+        }
+        plan.state = opts.entitlement.status === 'offline_grace' ? 'offline_grace' : 'ready';
+        plan.required_action = opts.entitlement.status === 'offline_grace' ? 'sync' : 'load';
+        plan.can_load_now = true;
+        plan.projection_policy = 'minimal';
+        if (opts.entitlement.status === 'offline_grace') {
+          plan.issues.push(buildLoadPlanIssue(
+            'KDNA_AUTH_OFFLINE_GRACE_ACTIVE',
+            'warning',
+            'The verified device grant can load offline but must sync before grace expires.',
+          ));
+        }
+        return finalizeLoadPlan(plan);
+      }
       plan.state = 'needs_account';
       plan.required_action = 'sign_in_or_activate';
       plan.can_load_now = false;
@@ -1448,6 +1521,16 @@ function planLoad(inputPath, opts = {}) {
     }
 
     if (plan.entitlement_profile === 'org') {
+      if (isVerifiedExternalEntitlement(opts.entitlement)) {
+        if (!externalEntitlementMatchesCurrentAsset(opts.entitlement)) {
+          return rejectExternalEntitlementMismatch();
+        }
+        plan.state = opts.entitlement.status === 'offline_grace' ? 'offline_grace' : 'ready';
+        plan.required_action = opts.entitlement.status === 'offline_grace' ? 'sync' : 'load';
+        plan.can_load_now = true;
+        plan.projection_policy = 'minimal';
+        return finalizeLoadPlan(plan);
+      }
       plan.state = 'needs_org_auth';
       plan.required_action = 'sign_in_or_activate';
       plan.can_load_now = false;
@@ -1621,26 +1704,22 @@ function assertNoForbiddenTerms(obj) {
 }
 
 module.exports = {
-  MIMETYPE: MIMETYPE_V1,
-  MIMETYPE_V1,
-  MIMETYPE_V2,
-  V1_REQUIRED_DIR_ENTRIES,
-  isV1SourceDir,
-  isV2SourceDir,
+  MIMETYPE,
+  REQUIRED_DIR_ENTRIES,
+  isKdnaSourceDir,
   detectContainerFormat,
-  readV1Layout,
+  readLayout: readV1Layout,
   inspect,
   validate,
   planLoad,
   loadAuthorized,
-  buildChecksumsV1,
+  buildChecksums: buildChecksumsV1,
   pack,
   unpack,
-  loadV1,
+  load: loadV1,
+  loadAsset: loadV1,
+  buildCapsule,
   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,
@@ -1742,8 +1821,11 @@ function loadAuthorized(inputPath, opts = {}) {
   const mergedOpts = {
     ...opts,
     resolvedDependencies: plan.resolved_dependencies,
-    // Pass extends_chain from plan to loadV1Unsafe so inheritance is applied (Story 12)
     extendsChain: plan.extends_chain || [],
+    _validation: {
+      schema_valid: plan.checks && plan.checks.overall_valid === true,
+      signature_valid: plan.signature_valid === true,
+    },
   };
   return loadV1Unsafe(inputPath, mergedOpts);
 }
@@ -1793,9 +1875,9 @@ function loadV1Unsafe(inputPath, opts = {}) {
   let payload;
   try {
     const rawPayload = v1.map['payload.kdnab'];
-    payload = parseJsonEntry('payload.kdnab', rawPayload);
+    payload = parsePayloadEntry("payload.kdnab", rawPayload);
   } catch (e) {
-    throw new Error(`payload.kdnab is not valid JSON: ${e.message}`, { cause: e });
+    throw new Error(`payload.kdnab is not valid KDNA payload: ${e.message}`, { cause: e });
   }
 
   if (payload.profile && payload.ciphertext && (m.payload?.encrypted || m.encryption?.encrypted_entries?.includes('payload.kdnab'))) {
@@ -1812,10 +1894,10 @@ function loadV1Unsafe(inputPath, opts = {}) {
         const decryptedBuf = typeof decrypted === 'string'
           ? Buffer.from(decrypted, 'utf8')
           : Buffer.from(decrypted);
-        payload = parseJsonEntry('payload.kdnab', decryptedBuf);
+        payload = parsePayloadEntry('payload.kdnab', decryptedBuf);
       } catch (e) {
         const err = new Error(`Decryption failed: ${e.message}`);
-        err.code = 'KDNA_DECRYPT_FAILED';
+        err.code = e.code || 'KDNA_DECRYPT_FAILED';
         throw err;
       }
     } else if (opts.password) {
@@ -1827,8 +1909,10 @@ function loadV1Unsafe(inputPath, opts = {}) {
           decryptProtectedEntryScrypt,
           PASSWORD_PROTECTED_SCRYPT_PROFILE,
         } = require('../crypto-profile.js');
-        const encryptedEnvelope = v1.map['payload.kdnab'].toString('utf8');
-        const envelope = JSON.parse(encryptedEnvelope);
+        const encryptedEnvelope = v1.map['payload.kdnab'];
+        let envelope;
+        try { envelope = cbor.decode(Buffer.isBuffer(encryptedEnvelope) ? encryptedEnvelope : Buffer.from(encryptedEnvelope)); }
+        catch { throw new Error('Cannot decode encrypted envelope: payload.kdnab must be CBOR-encoded (kdna_version 1.0)'); }
         const decryptFn = (envelope.profile === PASSWORD_PROTECTED_SCRYPT_PROFILE)
           ? decryptProtectedEntryScrypt
           : decryptProtectedEntry;
@@ -1837,15 +1921,20 @@ function loadV1Unsafe(inputPath, opts = {}) {
           manifest: m,
           password: opts.password,
         });
-        payload = parseJsonEntry('payload.kdnab', decryptedBuf);
+        payload = parsePayloadEntry('payload.kdnab', decryptedBuf);
       } catch (e) {
         const err = new Error(`Decryption failed with provided password: ${e.message}`);
         err.code = 'KDNA_DECRYPT_FAILED';
         throw err;
       }
     } else {
-      const err = new Error('payload is encrypted and cannot be decrypted without a password or license key');
-      err.code = 'KDNA_AUTH_PASSWORD_REQUIRED';
+      const isExternal = payload.profile === EXTERNAL_ENVELOPE_PROFILE;
+      const err = new Error(
+        isExternal
+          ? 'payload requires a verified account/device external key grant'
+          : 'payload is encrypted and cannot be decrypted without an authorized credential',
+      );
+      err.code = isExternal ? 'KDNA_AUTH_ACCOUNT_REQUIRED' : 'KDNA_AUTH_PASSWORD_REQUIRED';
       throw err;
     }
   }
@@ -1876,7 +1965,7 @@ function loadV1Unsafe(inputPath, opts = {}) {
     const hasJudgment = (core.axioms && core.axioms.length > 0)
       || (core.boundaries && core.boundaries.length > 0)
       || (payload.patterns && payload.patterns.length > 0)
-      || (payload.reasoning && ((payload.reasoning.self_checks && payload.reasoning.self_checks.length > 0) || (payload.reasoning.failure_modes && payload.reasoning.failure_modes.length > 0)));
+      || (payload.reasoning && ((payload.reasoning.self_check && payload.reasoning.self_check.length > 0) || (payload.reasoning.failure_modes && payload.reasoning.failure_modes.length > 0)));
     profiles.push('index');
     if (hasJudgment) profiles.push('compact');
     if (payload.scenarios && payload.scenarios.length > 0) profiles.push('scenario');
@@ -1911,7 +2000,11 @@ function loadV1Unsafe(inputPath, opts = {}) {
       highest_question: core.highest_question || null,
       axioms: (core.axioms || []).map(normalizeCompactAxiom).filter(Boolean),
       boundaries: normalizeList(core.boundaries),
-      self_checks: normalizeList(payload.reasoning && payload.reasoning.self_checks),
+      // The canonical payload field is singular (`reasoning.self_check`).
+      // Runtime Capsule uses plural (`context.self_checks`) as its projection
+      // field. Reading the plural name from the payload silently discarded
+      // every Studio-authored self-check.
+      self_checks: normalizeList(payload.reasoning && payload.reasoning.self_check),
       failure_modes: normalizeList(payload.reasoning && payload.reasoning.failure_modes),
       patterns: normalizeList(payload.patterns).slice(0, 3),
     };
@@ -1938,8 +2031,9 @@ function loadV1Unsafe(inputPath, opts = {}) {
         resolvedDependencies: [],
         extendsChain: [],
       });
-      if (baseLoaded && baseLoaded.content) {
-        const bc = baseLoaded.content;
+      const baseContent = baseLoaded && (baseLoaded.content || baseLoaded.context);
+      if (baseContent) {
+        const bc = baseContent;
         const cc = result.content;
         // Merge axioms: child overrides by id; parent axioms not in child are added
         if (bc.axioms || cc.axioms) {
@@ -2048,9 +2142,65 @@ function loadV1Unsafe(inputPath, opts = {}) {
     return { status: result.status, profile: result.profile, text: textOut };
   }
 
+  if (as === 'prompt') {
+    return result;
+  }
+
+  return wrapAsCapsule(result, v1, profile, opts);
+}
+
+function wrapAsCapsule(result, v1, profile, opts) {
+  if (opts.as === 'json') {
+    return buildCapsule(result, v1, profile, opts);
+  }
   return result;
 }
 
+function buildCapsule(loadResult, v1, profile, opts = {}) {
+  const m = v1.manifest;
+  const val = opts._validation || {};
+  const assetDigest = v1.assetDigest || (v1.map && v1.map['checksums.json']
+    ? (() => {
+        try {
+          const checks = JSON.parse(v1.map['checksums.json'].toString('utf8'));
+          return checks.asset_digest || null;
+        } catch { return null; }
+      })()
+    : null);
+
+  const pubkey = (m.creator && m.creator.pubkey) || (m.author && m.author.pubkey) || null;
+  const sigVerified = val.signature_valid === true;
+  const capsule = {
+    type: 'kdna.context.capsule',
+    version: '1.0',
+    domain: m.name || m.asset_id || null,
+    judgment_version: m.judgment_version || null,
+    asset_digest: assetDigest,
+    signature: pubkey
+      ? { state: sigVerified ? 'verified' : 'not_checked', issuer: pubkey }
+      : { state: 'absent' },
+    access: m.access || 'public',
+    risk_level: m.risk_level || null,
+    profile: loadResult.profile,
+    context: loadResult.content || {},
+    trace: {
+      payload_encoding: (m.payload && m.payload.encoding) || 'cbor',
+      loaded_by: 'kdna-core',
+      loaded_at: new Date().toISOString(),
+      schema_valid: val.schema_valid === true,
+      signature_state: sigVerified ? 'verified' : (pubkey ? 'not_checked' : 'absent'),
+      profile: profile,
+    },
+  };
+
+  if (loadResult.extends_chain) capsule.extends_chain = loadResult.extends_chain;
+  if (loadResult.inheritance_applied !== undefined) capsule.inheritance_applied = loadResult.inheritance_applied;
+  if (loadResult.resolved_dependencies) capsule.resolved_dependencies = loadResult.resolved_dependencies;
+  if (loadResult.rag_isolation_policy) capsule.rag_isolation_policy = loadResult.rag_isolation_policy;
+
+  return capsule;
+}
+
 // ─── Semver & Dependency Resolution (Story 6) ─────────────────────────
 
 function parseSemver(v) {

package/src/v1/index.mjs

@@ -1,21 +1,20 @@
 import v1 from './index.js';
 
 export const MIMETYPE = v1.MIMETYPE;
-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 REQUIRED_DIR_ENTRIES = v1.REQUIRED_DIR_ENTRIES;
+export const isKdnaSourceDir = v1.isKdnaSourceDir;
 export const detectContainerFormat = v1.detectContainerFormat;
-export const readV1Layout = v1.readV1Layout;
+export const readLayout = v1.readLayout;
 export const inspect = v1.inspect;
 export const validate = v1.validate;
 export const planLoad = v1.planLoad;
 export const loadAuthorized = v1.loadAuthorized;
-export const buildChecksumsV1 = v1.buildChecksumsV1;
+export const buildChecksums = v1.buildChecksums;
 export const pack = v1.pack;
 export const unpack = v1.unpack;
-export const loadV1 = v1.loadV1;
+export const load = v1.load;
+export const loadAsset = v1.loadAsset;
+export const buildCapsule = v1.buildCapsule;
 export const FORBIDDEN_OUTPUT_TERMS = v1.FORBIDDEN_OUTPUT_TERMS;
 
 export default v1;