@aikdna/kdna-core 0.15.11 → 0.15.12

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## v0.15.12 (2026-07-12)
+
+**Single-format refactor + CBOR wire contract + Runtime Capsule.**
+
+### Breaking changes
+
+- `MIMETYPE_V1`, `MIMETYPE_V2`, `MIMETYPE_LEGACY`, `isV1SourceDir`, `isV2SourceDir`
+  removed from public API. Use `MIMETYPE`, `isKdnaSourceDir`, `detectContainerFormat`.
+- `detectContainerFormat` returns only `"kdna"` or `null`.
+- `kdna_version: "2.0"` is no longer accepted. Only `"1.0"`.
+- `payload.encoding` accepts only `"cbor"`. JSON payload bytes are rejected;
+  there is no production JSON fallback.
+- Version-qualified public APIs (`V1_REQUIRED_DIR_ENTRIES`, `readV1Layout`,
+  `buildChecksumsV1`, `loadV1`, and the `./v1` export) are removed. Use the
+  unversioned APIs below.
+- `kdna load --as=json` now returns Runtime Capsule format
+  (`type: "kdna.context.capsule"`) instead of raw `{status, content}`.
+
+### Added
+
+- `REQUIRED_DIR_ENTRIES`, `readLayout`, `buildChecksums`, `load`, and
+  `loadAsset` are the sole public container/loading APIs.
+- `buildCapsule(loadResult, v1, profile, opts)` — wraps load output as
+  `kdna.context.capsule` per `specs/runtime-capsule.md`.
+- `parsePayloadEntry` — strict CBOR decoding for `payload.kdnab`.
+
+### Fixes
+
+- Producer/consumer encoding alignment: `dev-pack.js`, `studio.js` write CBOR;
+  validation and loading decode CBOR, including encrypted envelopes.
+- `loadV1Unsafe` extends/deps processing occurs before Capsule wrapping (Story 12 fix).
+- All test fixtures converted to CBOR; golden files regenerated.
+
 ## v0.15.11 (2026-07-03)
 
 **Fix**: repair Core v1 container dispatcher module resolution in the

package/README.md

@@ -1,10 +1,9 @@
 # @aikdna/kdna-core
 
-Core library for local `.kdna` judgment assets.
-
-KDNA Core v1 defines the `.kdna` file format, schemas, secure container
-reader, LoadPlan contract, and runtime projection helpers used by the CLI,
-Studio export, skills, MCP integrations, and downstream agent runtimes.
+Core library for `.kdna` judgment assets. It implements the single KDNA Asset
+Container, strict-CBOR payload decoding, validation, LoadPlan authorization,
+and Runtime Capsule projection used by the CLI, Studio, skills, MCP
+integrations, and downstream Agent runtimes.
 
 ## Installation
 
@@ -18,9 +17,10 @@ If you need full JSON Schema validation through Ajv, also install:
 npm install ajv ajv-formats
 ```
 
-## KDNA Core v1 API
+## Public API
 
-Use the `./v1` entrypoint for current KDNA Core v1 tooling:
+Use the package root. Version-qualified entrypoints and API names are not part
+of the public contract.
 
 ```js
 const {
@@ -30,8 +30,8 @@ const {
   loadAuthorized,
   pack,
   unpack,
-  buildChecksumsV1
-} = require('@aikdna/kdna-core/v1');
+  buildChecksums
+} = require('@aikdna/kdna-core');
 
 const validation = validate('./asset.kdna');
 if (!validation.overall_valid) {
@@ -43,10 +43,14 @@ if (plan.can_load_now !== true) {
   throw new Error(`Asset is not loadable yet: ${plan.required_action}`);
 }
 
-const compact = loadAuthorized('./asset.kdna', {
+const capsule = loadAuthorized('./asset.kdna', {
   profile: 'compact',
-  as: 'prompt'
+  as: 'json'
 });
+
+if (capsule.type !== 'kdna.context.capsule') {
+  throw new Error('Expected a Runtime Capsule');
+}
 ```
 
 ## Supported Runtime Flow
@@ -56,7 +60,8 @@ const compact = loadAuthorized('./asset.kdna', {
 → validate
 → planLoad
 → loadAuthorized
-→ agent/runtime context
+→ Runtime Capsule
+→ Agent/runtime context
 ```
 
 For authoring and test fixtures, `pack()` can turn a local working folder into
@@ -71,9 +76,9 @@ local working folder
 → loadAuthorized
 ```
 
-## v1 Container
+## KDNA Asset Container
 
-A v1 `.kdna` container contains:
+A `.kdna` asset contains:
 
 - `mimetype`
 - `kdna.json`
@@ -88,6 +93,10 @@ A v1 `.kdna` container contains:
 - checksum consistency
 - load-profile contract
 
+`payload.kdnab` is CBOR. A password-protected or licensed asset stores a CBOR
+encryption envelope in the same entry; authorized plaintext is decrypted in
+memory and projected into the Runtime Capsule.
+
 ## Load Profiles
 
 `loadAuthorized()` supports:
@@ -104,15 +113,9 @@ Output formats:
 
 ## Boundary
 
-KDNA Core v1 is content-neutral. It validates file structure and loadability;
+KDNA Core is content-neutral. It validates file structure and loadability;
 it does not rank judgment quality or endorse specific assets.
 
-## Legacy API
-
-The package root still exports compatibility APIs for older KDNA paths. New
-tooling should prefer `@aikdna/kdna-core/v1` and the `planLoad` /
-`loadAuthorized` path.
-
 ## License
 
 Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@aikdna/kdna-core",
-    "version": "0.15.11",
+    "version": "0.15.12",
     "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
     "engines": {
         "node": ">=18.0.0"
@@ -15,12 +15,7 @@
             "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"
-        }
+        "./schema/*": "./schema/*"
     },
     "types": "src/types.d.ts",
     "scripts": {

package/schema/manifest.schema.json

@@ -22,8 +22,8 @@
   "properties": {
     "kdna_version": {
       "type": "string",
-      "description": "KDNA Core version this manifest conforms to.",
-      "enum": ["1.0", "2.0"]
+      "description": "KDNA Asset Container wire discriminator.",
+      "enum": ["1.0"]
     },
     "asset_id": {
       "type": "string",
@@ -102,7 +102,7 @@
       "additionalProperties": true,
       "properties": {
         "path": { "type": "string", "const": "payload.kdnab" },
-        "encoding": { "type": "string", "enum": ["json", "cbor"] },
+        "encoding": { "type": "string", "enum": ["cbor"] },
         "encrypted": { "type": "boolean" }
       }
     },

package/src/asset-reader.js

@@ -8,7 +8,7 @@ const zlib = require('zlib');
 const cbor = require('cbor-x');
 const { loadDomainFromFiles, formatContext } = require('./loader');
 
-const KDNA_MEDIA_TYPE = 'application/vnd.aikdna.kdna+zip';
+const KDNA_MEDIA_TYPE = 'application/vnd.kdna.asset';
 
 // Standard KDNA domain data entries — kept in lockstep with loader.FILE_MAP.
 // Asset reader pre-loads these so callers don't have to enumerate entry names.
@@ -363,19 +363,18 @@ function verifyHumanLockSignatures(coreData, manifest, errors, warnings) {
 
 function validateManifestIdentity(manifest, errors, _warnings) {
   if (manifest.kdna_spec) {
-    errors.push('kdna.json: kdna_spec is not allowed. Use spec_version.');
+    errors.push('kdna.json: kdna_spec is not allowed. Use kdna_version.');
   }
   if (manifest.format && manifest.format !== 'kdna') {
     errors.push(`kdna.json.format: invalid value "${manifest.format}". Expected "kdna".`);
   }
-  if (manifest.format_version && manifest.format_version !== '2.0') {
+  if (!manifest.kdna_version) {
+    errors.push('kdna.json: missing required field "kdna_version"');
+  } else if (manifest.kdna_version !== '1.0') {
     errors.push(
-      `kdna.json.format_version: invalid value "${manifest.format_version}". Expected "2.0".`,
+      `kdna.json.kdna_version: invalid value "${manifest.kdna_version}". Expected "1.0".`,
     );
   }
-  if (!manifest.spec_version) errors.push('kdna.json: missing required field "spec_version"');
-  if (!manifest.format) errors.push('kdna.json: missing required field "format"');
-  if (!manifest.format_version) errors.push('kdna.json: missing required field "format_version"');
   if (manifest.language) {
     errors.push('kdna.json: language is not allowed. Use default_language and languages.');
   }
@@ -624,10 +623,7 @@ function createKdnaAssetReader() {
 
       if (!asset.entries.has('kdna.json')) errors.push('required entry missing: kdna.json');
       verifyMediaType(asset, errors);
-      if (!asset.entries.has('KDNA_Core.json')) errors.push('required entry missing: KDNA_Core.json');
-      if (!asset.entries.has('KDNA_Patterns.json')) {
-        errors.push('required entry missing: KDNA_Patterns.json');
-      }
+      if (!asset.entries.has('payload.kdnab')) errors.push('required entry missing: payload.kdnab');
 
       const content_digest = buildContentDigest(asset);
       const asset_digest = asset.asset_digest;

package/src/container-dispatcher.js

@@ -4,45 +4,25 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 
-const { createKdnaAssetReader } = require('./asset-reader.js');
-
-const MIMETYPE_V1 = 'application/vnd.kdna.asset';
-const MIMETYPE_V2 = 'application/vnd.aikdna.kdna+zip';
+const MIMETYPE = 'application/vnd.kdna.asset';
 
 /**
- * CanonicalAssetModel — the single internal representation of any KDNA asset,
- * regardless of whether it came from a source directory, Container v1,
- * or Canonical Distribution Container (Container v2 / SPEC 2.0).
- *
- * All downstream code (planLoad, loadAuthorized, decrypt, loadV1Unsafe)
- * operates on this model. No consumer should check container format directly.
+ * CanonicalAssetModel — the single internal representation of a KDNA asset,
+ * regardless of source (directory or .kdna container).
  *
  * @typedef {object} CanonicalAssetModel
- * @property {'dir'|'file'} sourceKind       — original input type
- * @property {string}       sourcePath       — resolved absolute path
- * @property {string}       format           — 'v1-dir' | 'v1-container' | 'v2-container'
- * @property {string}       mimetype         — normalized mimetype
+ * @property {'dir'|'file'} sourceKind
+ * @property {string}       sourcePath
+ * @property {string}       format           — 'dir' | 'kdna'
+ * @property {string}       mimetype
  * @property {object}       manifest         — parsed kdna.json
- * @property {Buffer}       payloadRaw       — raw payload.kdnab bytes (CBOR/JSON)
- * @property {object|null}  checksums        — parsed checksums.json, or null
- * @property {Buffer|null}  assetDigest      — SHA-256 of entire container (file only)
- * @property {Buffer|null}  containerBuffer  — full container bytes (for ZIP inputs, may be null for dirs)
- * @property {Map<string, Buffer>|null} entries — raw entry map (for v1 dir layout; null for v2/container)
+ * @property {Buffer}       payloadRaw       — raw payload.kdnab bytes
+ * @property {object|null}  checksums
+ * @property {Buffer|null}  assetDigest
+ * @property {Buffer|null}  containerBuffer
+ * @property {Map<string, Buffer>|null} entries
  */
 
-/**
- * Read any KDNA asset into a CanonicalAssetModel.
- *
- * Handles:
- *   - Source directories (mimetype + kdna.json + payload.kdnab on disk)
- *   - Container v1 (.kdna ZIP with application/vnd.kdna.asset mimetype)
- *   - Canonical containers (.kdna ZIP with application/vnd.aikdna.kdna+zip mimetype)
- *
- * @param {string} inputPath - absolute path to asset file or directory
- * @param {object} [opts]
- * @param {object} [opts.limits] - container size/entry limits
- * @returns {CanonicalAssetModel}
- */
 function readAsset(inputPath, opts = {}) {
   const absPath = path.resolve(inputPath);
   const stat = fs.statSync(absPath);
@@ -59,11 +39,8 @@ function readAsset(inputPath, opts = {}) {
   }
 
   const format = detectFormat(absPath);
-  if (format === 'v1-container') {
-    return readV1Container(absPath, opts);
-  }
-  if (format === 'v2-container') {
-    return readV2Container(absPath, opts);
+  if (format === 'kdna') {
+    return readKdnaContainer(absPath, opts);
   }
 
   throw Object.assign(
@@ -72,10 +49,6 @@ function readAsset(inputPath, opts = {}) {
   );
 }
 
-/**
- * Detect the container format of a .kdna file.
- * Returns 'v1-container', 'v2-container', or throws.
- */
 function detectFormat(absPath) {
   const buf = fs.readFileSync(absPath);
   if (buf.length < 4) {
@@ -85,7 +58,6 @@ function detectFormat(absPath) {
     );
   }
 
-  // Must be a ZIP (PK signature)
   const sig = buf.readUInt32LE(0);
   if (sig !== 0x04034b50) {
     throw Object.assign(
@@ -94,7 +66,6 @@ function detectFormat(absPath) {
     );
   }
 
-  // Read the mimetype from the first entry (central directory first entry)
   const eocdOffset = findEocd(buf);
   let cdOffset = buf.readUInt32LE(eocdOffset + 16);
   const cdEntryCount = buf.readUInt16LE(eocdOffset + 10);
@@ -126,8 +97,7 @@ function detectFormat(absPath) {
     const compressedSize = buf.readUInt32LE(entryOffset + 20);
     const mime = buf.toString('utf8', dataOffset, dataOffset + compressedSize).trim();
 
-    if (mime === MIMETYPE_V1) return 'v1-container';
-    if (mime === MIMETYPE_V2) return 'v2-container';
+    if (mime === MIMETYPE) return 'kdna';
 
     throw Object.assign(
       new Error(`Unknown KDNA mimetype: ${mime}`),
@@ -154,9 +124,6 @@ function findEocd(buf) {
   );
 }
 
-/**
- * Read a source directory into CanonicalAssetModel.
- */
 function readSourceDirectory(absPath, _opts) {
   const mimetypePath = path.join(absPath, 'mimetype');
   const manifestPath = path.join(absPath, 'kdna.json');
@@ -171,7 +138,7 @@ function readSourceDirectory(absPath, _opts) {
   }
 
   const mimetype = fs.readFileSync(mimetypePath, 'utf8').trim();
-  if (![MIMETYPE_V1, MIMETYPE_V2].includes(mimetype)) {
+  if (mimetype !== MIMETYPE) {
     throw Object.assign(
       new Error(`Unknown mimetype in source directory: ${mimetype}`),
       { code: 'KDNA_FORMAT_UNKNOWN' },
@@ -204,7 +171,7 @@ function readSourceDirectory(absPath, _opts) {
   return {
     sourceKind: 'dir',
     sourcePath: absPath,
-    format: 'v1-dir',
+    format: 'dir',
     mimetype,
     manifest,
     payloadRaw,
@@ -215,21 +182,16 @@ function readSourceDirectory(absPath, _opts) {
   };
 }
 
-/**
- * Read a Container v1 (.kdna with v1 mimetype) into CanonicalAssetModel.
- */
-function readV1Container(absPath, _opts) {
-  // Delegate to the existing v1 layout reader for validation
-  const v1Layout = require('./v1/index.js').readV1Layout(absPath);
-
+function readKdnaContainer(absPath, _opts) {
+  const v1Layout = require('./v1/index.js').readLayout(absPath);
   const containerBuf = fs.readFileSync(absPath);
   const assetDigest = crypto.createHash('sha256').update(containerBuf).digest();
 
   return {
     sourceKind: 'file',
     sourcePath: absPath,
-    format: 'v1-container',
-    mimetype: MIMETYPE_V1,
+    format: 'kdna',
+    mimetype: MIMETYPE,
     manifest: v1Layout.manifest,
     payloadRaw: v1Layout.map['payload.kdnab'] || null,
     checksums: v1Layout.map['checksums.json']
@@ -241,58 +203,18 @@ function readV1Container(absPath, _opts) {
   };
 }
 
-/**
- * Read a Canonical Container (v2 mimetype) into CanonicalAssetModel.
- * Uses the existing KdnaAssetReader for ZIP parsing.
- */
-function readV2Container(absPath, _opts) {
-  const reader = createKdnaAssetReader();
-  const asset = reader.openSync(absPath);
-
-  const manifest = reader.readManifestSync(asset);
-  const payloadRaw = reader.readEntrySync(asset, 'payload.kdnab');
-  const checksums = (() => {
-    try {
-      const raw = reader.readEntrySync(asset, 'checksums.json');
-      return raw ? JSON.parse(raw.toString('utf8')) : null;
-    } catch {
-      return null;
-    }
-  })();
-
-  return {
-    sourceKind: 'file',
-    sourcePath: absPath,
-    format: 'v2-container',
-    mimetype: MIMETYPE_V2,
-    manifest,
-    payloadRaw,
-    checksums,
-    assetDigest: Buffer.from(asset.asset_digest.replace(/^sha256:/, ''), 'hex'),
-    containerBuffer: fs.readFileSync(absPath),
-    entries: null, // v2 uses lazy reads, not pre-loaded map
-  };
-}
-
-/**
- * Extract the mimetype from a CanonicalAssetModel.
- */
 function getMimetype(asset) {
   return asset.mimetype;
 }
 
-/**
- * Determine if a CanonicalAssetModel represents a source directory.
- */
-function isSourceDirectory(asset) {
+function isKdnaSourceDirectory(asset) {
   return asset.sourceKind === 'dir';
 }
 
 module.exports = {
-  MIMETYPE_V1,
-  MIMETYPE_V2,
+  MIMETYPE,
   readAsset,
   detectFormat,
   getMimetype,
-  isSourceDirectory,
+  isKdnaSourceDirectory,
 };

package/src/crypto-profile.js

@@ -1,4 +1,5 @@
 const crypto = require('crypto');
+const cbor = require('cbor-x');
 
 let argon2id;
 try {
@@ -56,11 +57,13 @@ function decodeBase64(value, label) {
 
 function normalizeEnvelope(value) {
   if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
-    return JSON.parse(Buffer.from(value).toString('utf8'));
+    try { return cbor.decode(Buffer.from(value)); } catch { /* fall through */ }
+  }
+  if (typeof value === 'string') {
+    try { return cbor.decode(Buffer.from(value, 'utf8')); } catch { /* fall through */ }
   }
-  if (typeof value === 'string') return JSON.parse(value);
   if (value && typeof value === 'object') return value;
-  throw new Error('encrypted entry envelope must be JSON');
+  throw new Error('encrypted entry envelope must be CBOR (kdna_version 1.0)');
 }
 
 function encryptedEntryAad(entryName, manifest = {}, profile = LICENSED_ENTRY_PROFILE) {

package/src/index.mjs

@@ -12,6 +12,28 @@ export {
 
 export { lintDomain } from './lint-pure.js';
 
+export {
+  MIMETYPE,
+  REQUIRED_DIR_ENTRIES,
+  isKdnaSourceDir,
+  detectContainerFormat,
+  readLayout,
+  inspect,
+  validate,
+  planLoad,
+  loadAuthorized,
+  buildChecksums,
+  pack,
+  unpack,
+  load,
+  loadAsset,
+  buildCapsule,
+  FORBIDDEN_OUTPUT_TERMS,
+  parseSemver,
+  compareSemver,
+  satisfies,
+} from './v1/index.js';
+
 export { validateDomainSchema, validateCrossFile } from './validate-pure.js';
 
 export { renderPreviewHTML, escHtml, renderCard } from './render.js';

package/src/lint-pure.js

@@ -273,13 +273,13 @@ const VALID_ASSET_TYPE = new Set([
 ]);
 
 const MANIFEST_REQUIRED = [
-  'format', 'format_version', 'spec_version', 'name', 'version',
+  'kdna_version', 'name', 'version',
   'judgment_version', 'description', 'author', 'license', 'status',
   'quality_badge', 'access', 'languages', 'default_language',
 ];
 
 /**
- * Validate a kdna.json manifest against the canonical v1.0-rc schema.
+ * Validate a kdna.json manifest against the canonical KDNA Asset format.
  *
  * @param {Object} manifest — parsed kdna.json
  * @returns {{ errors: string[], warnings: string[] }}
@@ -296,7 +296,7 @@ function validateManifest(manifest) {
   // 1. Check disallowed pre-v1.0 manifest aliases
   if ('kdna_spec' in manifest) {
     errors.push(
-      'kdna.json: kdna_spec is not allowed. Use spec_version.',
+      'kdna.json: kdna_spec is not allowed. Use kdna_version.',
     );
   }
   if ('language' in manifest) {
@@ -319,9 +319,11 @@ function validateManifest(manifest) {
   if (manifest.format && manifest.format !== 'kdna') {
     errors.push(`kdna.json.format: invalid value "${manifest.format}". Expected "kdna".`);
   }
-  if (manifest.format_version && manifest.format_version !== '2.0') {
+  if (!manifest.kdna_version) {
+    errors.push('kdna.json: missing required field "kdna_version"');
+  } else if (manifest.kdna_version !== '1.0') {
     errors.push(
-      `kdna.json.format_version: invalid value "${manifest.format_version}". Expected "2.0".`,
+      `kdna.json.kdna_version: invalid value "${manifest.kdna_version}". Expected "1.0".`,
     );
   }
   if (manifest.status && !VALID_STATUS.has(manifest.status)) {
@@ -394,14 +396,7 @@ function validateManifest(manifest) {
     errors.push('kdna.json.license: missing "type"');
   }
 
-  // 9. Validate spec_version value
-  if (manifest.spec_version && manifest.spec_version !== '1.0-rc') {
-    warnings.push(
-      `kdna.json.spec_version: non-standard value "${manifest.spec_version}". Expected "1.0-rc".`,
-    );
-  }
-
-  // 10. Validate version format
+  // 9. Validate version format
   if (manifest.version && !/^\d+\.\d+\.\d+/.test(manifest.version)) {
     warnings.push(
       `kdna.json.version: non-semver format "${manifest.version}". Expected MAJOR.MINOR.PATCH.`,

package/src/types.d.ts

@@ -203,9 +203,7 @@ export interface KDNAFileDataMap {
 }
 
 export interface KDNAManifest {
-  format: 'kdna';
-  format_version: '2.0';
-  spec_version: string;
+  kdna_version: '1.0';
   name: string;
   version: string;
   judgment_version: string;
@@ -484,36 +482,33 @@ export function matchDomain(input: string, candidates: Array<KDNAAssetInput | KD
 export function matchDomainSync(input: string, candidates: Array<KDNAAssetInput | KDNAInspectResult>, options?: KdnaDecryptOptions): KDNAMatchResult[];
 export function composeKDNA(inputs: KDNAAssetInput[], options?: { input?: string; profile?: 'compact' | 'scenario' | 'full' | string; separator?: string } & KdnaDecryptOptions): Promise<KDNAComposeResult>;
 
-// KDNA Core v1 — source directory / container API
+// KDNA Core — source directory / container API
 export const MIMETYPE: string;
-export const MIMETYPE_V1: string;
-export const MIMETYPE_V2: string;
-export const V1_REQUIRED_DIR_ENTRIES: string[];
+export const REQUIRED_DIR_ENTRIES: string[];
 
-export interface KDNAV1ChecksumEntry {
+export interface KDNAChecksumEntry {
   algorithm: 'sha256';
   value: string;
 }
 
-export interface KDNAV1Checksums {
+export interface KDNAChecksums {
   algorithm: 'sha256';
   manifest_digest: string;
   payload_digest: string;
   asset_digest: string;
-  entries: Record<string, KDNAV1ChecksumEntry>;
+  entries: Record<string, KDNAChecksumEntry>;
 }
 
-export function isV1SourceDir(inputPath: string): boolean;
-export function isV2SourceDir(inputPath: string): boolean;
-export function detectContainerFormat(inputPath: string): 'v1' | 'v2' | null;
+export function isKdnaSourceDir(inputPath: string): boolean;
+export function detectContainerFormat(inputPath: string): 'kdna' | 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>;
-export interface KDNAV1LoadPlanIssue {
+export interface KDNALoadPlanIssue {
   code: string;
   severity: 'info' | 'warning' | 'blocking' | string;
   message: string;
 }
-export interface KDNAV1LoadPlan {
+export interface KDNALoadPlan {
   kdna_version: string | null;
   asset: {
     asset_id: string | null;
@@ -552,18 +547,19 @@ export interface KDNAV1LoadPlan {
   projection_policy: 'minimal' | 'remote' | 'none' | string;
   input_fingerprint: string | null;
   checks: Record<string, boolean>;
-  issues: KDNAV1LoadPlanIssue[];
+  issues: KDNALoadPlanIssue[];
   source: {
     kind: 'dir' | 'file' | string | null;
     path: string;
   };
 }
-export function planLoad(inputPath: string, options?: { password?: string; hasPassword?: boolean; entitlement?: Record<string, any> }): KDNAV1LoadPlan;
-export function buildChecksumsV1(sourceDir: string): KDNAV1Checksums;
+export function planLoad(inputPath: string, options?: { password?: string; hasPassword?: boolean; entitlement?: Record<string, any> }): KDNALoadPlan;
+export function buildChecksums(sourceDir: string): KDNAChecksums;
 export function pack(sourceDir: string, outputPath: string): void;
 export function unpack(inputPath: string, outputDir: string): void;
 export function loadAuthorized(inputPath: string, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; as?: 'json' | 'prompt' | string }): Record<string, any>;
-export function loadV1(inputPath: string, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; as?: 'json' | 'prompt' | string }): Record<string, any>;
+export function load(inputPath: string, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; as?: 'json' | 'prompt' | string }): Record<string, any>;
+export function loadAsset(inputPath: string, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; as?: 'json' | 'prompt' | string }): Record<string, any>;
 export const FORBIDDEN_OUTPUT_TERMS: readonly string[];
 
 // Lint

package/src/v1/index.js

@@ -38,24 +38,24 @@ 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 { 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 +64,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,
@@ -176,45 +182,28 @@ function loadSchemas() {
  * 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 +211,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 ────────────────────────────────────────────────────────────
@@ -599,9 +585,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 +643,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 +714,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}`);
     }
   }
 
@@ -736,10 +740,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);
   }
 
@@ -931,12 +935,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 +960,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;
@@ -1011,9 +1025,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);
@@ -1621,26 +1635,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 +1752,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 +1806,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,7 +1825,7 @@ 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';
@@ -1827,8 +1840,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,7 +1852,7 @@ 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';
@@ -1938,8 +1953,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 +2064,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;