@aikdna/kdna-core 0.18.0 → 0.19.0

package/src/loader-compatibility.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { version: KDNA_LOADER_VERSION } = require('../package.json');
+
+const STRICT_LOADER_VERSION = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/u;
+
+function parseLoaderVersion(value) {
+  if (typeof value !== 'string') return null;
+  const match = STRICT_LOADER_VERSION.exec(value);
+  return match ? Object.freeze(match.slice(1)) : null;
+}
+
+function compareNumericIdentifier(left, right) {
+  if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function compareLoaderVersions(leftVersion, rightVersion) {
+  const left = parseLoaderVersion(leftVersion);
+  const right = parseLoaderVersion(rightVersion);
+  if (!left || !right) {
+    throw new TypeError('loader versions must use strict x.y.z SemVer without leading zeros');
+  }
+  for (let index = 0; index < 3; index += 1) {
+    const comparison = compareNumericIdentifier(left[index], right[index]);
+    if (comparison !== 0) return comparison;
+  }
+  return 0;
+}
+
+if (!parseLoaderVersion(KDNA_LOADER_VERSION)) {
+  throw new Error(`@aikdna/kdna-core package version is not a strict loader coordinate: ${KDNA_LOADER_VERSION}`);
+}
+
+function assessLoaderCompatibility(manifest) {
+  const requiredValue = manifest?.compatibility?.min_loader_version;
+  const required = parseLoaderVersion(requiredValue);
+  return Object.freeze({
+    loader_version: KDNA_LOADER_VERSION,
+    min_loader_version: typeof requiredValue === 'string' ? requiredValue : null,
+    loader_compatible: required
+      ? compareLoaderVersions(requiredValue, KDNA_LOADER_VERSION) <= 0
+      : null,
+  });
+}
+
+function loaderVersionUnsupportedMessage(requiredVersion) {
+  return `KDNA_LOADER_VERSION_UNSUPPORTED: asset requires loader ${requiredVersion}, current loader is ${KDNA_LOADER_VERSION}`;
+}
+
+module.exports = {
+  KDNA_LOADER_VERSION,
+  STRICT_LOADER_VERSION,
+  parseLoaderVersion,
+  compareLoaderVersions,
+  assessLoaderCompatibility,
+  loaderVersionUnsupportedMessage,
+};

package/src/loader.js

@@ -157,7 +157,7 @@ function detectOldFieldNames(obj, path = '', warnings = []) {
   for (const key of Object.keys(obj)) {
     if (FIELD_ALIASES[key]) {
       warnings.push(
-        `[KDNA LOADER] ${path}.${key}: field "${key}" is not in spec v0.4. Use "${FIELD_ALIASES[key]}" instead. See docs/authoring-guide.md §0.`,
+        `[KDNA LOADER] ${path}.${key}: field "${key}" is not in spec 0.4. Use "${FIELD_ALIASES[key]}" instead. See docs/authoring-guide.md §0.`,
       );
     }
     if (typeof obj[key] === 'object' && obj[key] !== null) {

package/src/public-api.js

@@ -9,7 +9,7 @@
 
 const fs = require('fs');
 const { createKdnaAssetReader } = require('./asset-reader');
-const v1 = require('./v1');
+const container = require('./container');
 const runtimeApi = require('./runtime-api');
 
 function readerFrom(options = {}) {
@@ -53,7 +53,7 @@ function openKDNASync(input, options = {}) {
 async function inspectKDNA(input, options = {}) {
   const reader = readerFrom(options);
   const asset = await asAsset(input, { ...options, reader });
-  const current = v1.inspect(canonicalBytes(asset), options);
+  const current = container.inspect(canonicalBytes(asset), options);
   const manifest = await reader.readManifest(asset);
   const entries = await reader.listEntries(asset);
   const contentDigest = await reader.contentDigest(asset);
@@ -74,7 +74,7 @@ async function inspectKDNA(input, options = {}) {
 function inspectKDNASync(input, options = {}) {
   const reader = readerFrom(options);
   const asset = asAssetSync(input, { ...options, reader });
-  const current = v1.inspect(canonicalBytes(asset), options);
+  const current = container.inspect(canonicalBytes(asset), options);
   const manifest = reader.readManifestSync(asset);
   const entries = reader.listEntriesSync(asset);
   const contentDigest = reader.contentDigestSync(asset);
@@ -101,11 +101,11 @@ function loadKDNASync(input, options = {}) {
 }
 
 async function validateKDNA(input, options = {}) {
-  return v1.validate(isAsset(input) ? canonicalBytes(input) : input, options);
+  return container.validate(isAsset(input) ? canonicalBytes(input) : input, options);
 }
 
 function validateKDNASync(input, options = {}) {
-  return v1.validate(isAsset(input) ? canonicalBytes(input) : input, options);
+  return container.validate(isAsset(input) ? canonicalBytes(input) : input, options);
 }
 
 async function renderForAgent(input, options = {}) {

package/src/remote-runtime.d.ts

@@ -0,0 +1,13 @@
+import type { KDNARuntimeCapsule } from './types';
+
+/** A final packaged `.kdna` file path or its immutable packaged bytes. */
+export type KDNARemoteRuntimeInput = string | Uint8Array;
+
+/**
+ * Load one deployer-controlled `access: "remote"` asset for server-side
+ * projection. The function always returns a full JSON Runtime Capsule and
+ * accepts no caller policy options.
+ */
+export function loadRemoteRuntimeAsset(
+  input: KDNARemoteRuntimeInput,
+): KDNARuntimeCapsule;

package/src/remote-runtime.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const container = require('./container');
+
+/**
+ * Load one deployer-controlled `access: "remote"` packaged asset for a
+ * server-side projection Runtime.
+ *
+ * This API intentionally accepts no caller policy options. Physical control
+ * of the packaged remote asset is the deployment authorization boundary; the
+ * embedding server remains responsible for request authentication,
+ * entitlement checks, projection minimization, and audit policy.
+ */
+function loadRemoteRuntimeAsset(input) {
+  if (arguments.length !== 1) {
+    const error = new Error(
+      'loadRemoteRuntimeAsset accepts exactly one packaged asset input and no caller policy options.',
+    );
+    error.code = 'KDNA_REMOTE_RUNTIME_OPTIONS_FORBIDDEN';
+    throw error;
+  }
+  return container.loadRemoteRuntimeAssetForServer(input);
+}
+
+module.exports = {
+  loadRemoteRuntimeAsset,
+};

package/src/remote-runtime.mjs

@@ -0,0 +1,3 @@
+import remoteRuntime from './remote-runtime.js';
+
+export const loadRemoteRuntimeAsset = remoteRuntime.loadRemoteRuntimeAsset;

package/src/runtime-api.js

@@ -2,12 +2,12 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const v1 = require('./v1');
+const container = require('./container');
 
 function invalidDirectoryPlan(inputPath) {
   const resolved = path.resolve(inputPath);
   return {
-    kdna_version: null,
+    format_version: null,
     asset: { asset_id: null, asset_uid: null, title: null, version: null, judgment_version: null },
     access: null,
     access_alias: null,
@@ -64,7 +64,7 @@ function guardResolver(options = {}) {
 
 function planLoad(inputPath, options = {}) {
   if (isDirectory(inputPath)) return invalidDirectoryPlan(inputPath);
-  return v1.planLoad(inputPath, guardResolver(options));
+  return container.planLoad(inputPath, guardResolver(options));
 }
 
 function loadAuthorized(inputPath, options = {}) {
@@ -77,9 +77,9 @@ function loadAuthorized(inputPath, options = {}) {
     error.plan = plan;
     throw error;
   }
-  // v1.loadAuthorized snapshots packaged paths once and uses that same Buffer
+  // container.loadAuthorized snapshots packaged paths once and uses that same Buffer
   // for its LoadPlan, authorization decision, and Runtime Capsule projection.
-  return v1.loadAuthorized(inputPath, guardResolver(options));
+  return container.loadAuthorized(inputPath, guardResolver(options));
 }
 
 module.exports = {