@aikdna/kdna-core 0.12.2 → 0.12.4

package/README.md

@@ -1,10 +1,10 @@
 # @aikdna/kdna-core
 
-Core library for KDNA judgment assets.
+Core library for local `.kdna` judgment assets.
 
-KDNA Core v1 defines the official `.kdna` source/container contract used by
-the CLI, Studio export, skills, MCP integrations, and downstream agent
-runtimes.
+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.
 
 ## Installation
 
@@ -26,9 +26,10 @@ Use the `./v1` entrypoint for current KDNA Core v1 tooling:
 const {
   inspect,
   validate,
+  planLoad,
+  loadAuthorized,
   pack,
   unpack,
-  loadV1,
   buildChecksumsV1
 } = require('@aikdna/kdna-core/v1');
 
@@ -37,7 +38,12 @@ if (!validation.overall_valid) {
   throw new Error(validation.problems.join('\n'));
 }
 
-const compact = loadV1('./asset.kdna', {
+const plan = planLoad('./asset.kdna');
+if (plan.can_load_now !== true) {
+  throw new Error(`Asset is not loadable yet: ${plan.required_action}`);
+}
+
+const compact = loadAuthorized('./asset.kdna', {
   profile: 'compact',
   as: 'prompt'
 });
@@ -46,26 +52,35 @@ const compact = loadV1('./asset.kdna', {
 ## Supported Runtime Flow
 
 ```text
-v1 source directory
-→ buildChecksumsV1
-→ pack
+.kdna file
 → validate
-→ loadV1
+→ planLoad
+→ loadAuthorized
 → agent/runtime context
 ```
 
-## v1 Source Directory
+For authoring and test fixtures, `pack()` can turn a local working folder into
+a `.kdna` file before validation:
+
+```text
+local working folder
+→ pack
+→ .kdna file
+→ validate
+→ planLoad
+→ loadAuthorized
+```
+
+## v1 Container
 
-A v1 source directory contains:
+A v1 `.kdna` container contains:
 
 - `mimetype`
 - `kdna.json`
 - `payload.kdnab`
 - `checksums.json`
 
-## v1 Container
-
-A v1 `.kdna` container is a zip package of the same files. `validate()` checks:
+`validate()` checks:
 
 - format
 - manifest schema
@@ -75,7 +90,7 @@ A v1 `.kdna` container is a zip package of the same files. `validate()` checks:
 
 ## Load Profiles
 
-`loadV1()` supports:
+`loadAuthorized()` supports:
 
 - `index`
 - `compact`
@@ -89,15 +104,14 @@ Output formats:
 
 ## Boundary
 
-KDNA Core v1 is content-neutral. It does not recommend assets, assign quality
-badges, run a marketplace, or define a public registry. Future signature,
-encryption, licensing, and entitlement work is gated outside the current v1
-baseline.
+KDNA Core v1 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`.
+tooling should prefer `@aikdna/kdna-core/v1` and the `planLoad` /
+`loadAuthorized` path.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.12.2",
-  "description": "KDNA core library — load, validate, lint, and render KDNA domain judgment assets. Supports KDNA Container format (payload.kdnab via CBOR).",
+  "version": "0.12.4",
+  "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
   "type": "commonjs",
   "main": "src/index.js",
   "module": "src/index.mjs",
@@ -35,7 +35,7 @@
     "kdna",
     "kdna-core",
     "ai-agent",
-    "domain-cognition"
+    "judgment-assets"
   ],
   "license": "Apache-2.0",
   "repository": {

package/schema/checksums.schema.json

@@ -6,6 +6,16 @@
   "type": "object",
   "required": ["algorithm"],
   "additionalProperties": true,
+  "$defs": {
+    "sha256Digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "sha256Value": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    }
+  },
   "properties": {
     "algorithm": {
       "type": "string",
@@ -13,19 +23,16 @@
       "enum": ["sha256", "sha512", "blake2b-256"]
     },
     "manifest_digest": {
-      "type": "string",
       "description": "Digest of the kdna.json entry.",
-      "pattern": "^[a-z0-9-]+:.+$"
+      "$ref": "#/$defs/sha256Digest"
     },
     "payload_digest": {
-      "type": "string",
       "description": "Digest of the payload.kdnab entry.",
-      "pattern": "^[a-z0-9-]+:.+$"
+      "$ref": "#/$defs/sha256Digest"
     },
     "asset_digest": {
-      "type": "string",
       "description": "Digest of the whole container (per-entry digests combined deterministically).",
-      "pattern": "^[a-z0-9-]+:.+$"
+      "$ref": "#/$defs/sha256Digest"
     },
     "entries": {
       "type": "object",
@@ -34,8 +41,8 @@
         "type": "object",
         "required": ["algorithm", "value"],
         "properties": {
-          "algorithm": { "type": "string" },
-          "value": { "type": "string" }
+          "algorithm": { "const": "sha256" },
+          "value": { "$ref": "#/$defs/sha256Value" }
         }
       }
     }

package/schema/load-plan.schema.json

@@ -14,6 +14,7 @@
     "required_action",
     "can_load_now",
     "projection_policy",
+    "input_fingerprint",
     "checks",
     "issues",
     "source"
@@ -73,6 +74,10 @@
       "type": "string",
       "enum": ["minimal", "remote", "none"]
     },
+    "input_fingerprint": {
+      "type": ["string", "null"],
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
     "checks": {
       "type": "object",
       "required": [

package/src/types.d.ts

@@ -549,6 +549,7 @@ export interface KDNAV1LoadPlan {
     | string;
   can_load_now: boolean;
   projection_policy: 'minimal' | 'remote' | 'none' | string;
+  input_fingerprint: string | null;
   checks: Record<string, boolean>;
   issues: KDNAV1LoadPlanIssue[];
   source: {
@@ -560,6 +561,7 @@ export function planLoad(inputPath: string, options?: { password?: string; hasPa
 export function buildChecksumsV1(sourceDir: string): KDNAV1Checksums;
 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 const FORBIDDEN_OUTPUT_TERMS: readonly string[];
 

package/src/v1/index.js

@@ -747,6 +747,7 @@ function verifyDigests(checksums, map, problems, result) {
     manifest_digest: 'kdna.json',
     payload_digest: 'payload.kdnab',
   };
+  const entryDigests = {};
   let stillValid = true;
   for (const [digestKey, entryName] of Object.entries(entryMap)) {
     const declared = checksums[digestKey];
@@ -758,12 +759,33 @@ function verifyDigests(checksums, map, problems, result) {
     }
     const entryBytes = map[entryName];
     const actual = crypto.createHash('sha256').update(entryBytes).digest('hex');
+    entryDigests[entryName] = actual;
     const expected = declared.replace(/^sha256:/, '');
     if (actual !== expected) {
       problems.push(`checksums: ${digestKey} mismatch (declared ${expected.slice(0, 8)}..., actual ${actual.slice(0, 8)}...)`);
       stillValid = false;
     }
   }
+  if (checksums.asset_digest) {
+    const expectedAssetDigest = checksums.asset_digest.replace(/^sha256:/, '');
+    const missingAssetInputs = ['kdna.json', 'payload.kdnab'].filter((entryName) => !entryDigests[entryName]);
+    if (missingAssetInputs.length) {
+      problems.push(`checksums: asset_digest cannot be verified without ${missingAssetInputs.join(', ')}`);
+      stillValid = false;
+    } else {
+      const combined = Object.keys(entryDigests)
+        .sort()
+        .map((name) => `${name}:${entryDigests[name]}`)
+        .join('\n');
+      const actualAssetDigest = crypto.createHash('sha256').update(combined).digest('hex');
+      if (actualAssetDigest !== expectedAssetDigest) {
+        problems.push(
+          `checksums: asset_digest mismatch (declared ${expectedAssetDigest.slice(0, 8)}..., actual ${actualAssetDigest.slice(0, 8)}...)`,
+        );
+        stillValid = false;
+      }
+    }
+  }
   if (!stillValid) result.checksums_valid = false;
   return stillValid;
 }
@@ -986,6 +1008,25 @@ function finalizeLoadPlan(plan) {
   return plan;
 }
 
+function inputFingerprint(inputPath, v1) {
+  const absPath = path.resolve(inputPath);
+  if (v1.kind === 'file') {
+    return `sha256:${crypto.createHash('sha256').update(fs.readFileSync(absPath)).digest('hex')}`;
+  }
+
+  const hash = crypto.createHash('sha256');
+  for (const name of Object.keys(v1.map).sort()) {
+    const bytes = v1.map[name];
+    hash.update(name);
+    hash.update('\0');
+    hash.update(String(bytes.length));
+    hash.update('\0');
+    hash.update(bytes);
+    hash.update('\0');
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
 function baseLoadPlan(inputPath, v1, validation) {
   const manifest = v1.manifest;
   const accessInfo = normalizeAccess(manifest.access);
@@ -1008,6 +1049,7 @@ function baseLoadPlan(inputPath, v1, validation) {
     required_action: 'block',
     can_load_now: false,
     projection_policy: 'none',
+    input_fingerprint: inputFingerprint(inputPath, v1),
     checks: {
       format_valid: validation.format_valid,
       schema_valid: validation.schema_valid,
@@ -1060,6 +1102,7 @@ function planLoad(inputPath, opts = {}) {
       required_action: 'block',
       can_load_now: false,
       projection_policy: 'none',
+      input_fingerprint: null,
       checks: {
         format_valid: false,
         schema_valid: false,