@aikdna/kdna-core 0.18.0 → 0.20.0

package/src/{capsule-v2.js → runtime-capsule.js}

@@ -3,18 +3,20 @@
 const crypto = require('node:crypto');
 const fs = require('node:fs');
 
-const Ajv2020 = require('ajv/dist/2020');
+const JsonSchema2020 = require('ajv/dist/2020');
 const addFormats = require('ajv-formats');
 
 const { createKdnaAssetReader } = require('./asset-reader');
-const v1 = require('./v1');
+const container = require('./container');
 const digestEvidenceSchema = require('../schema/digest-evidence.schema.json');
-const capsule1Schema = require('../schema/runtime-capsule-1.schema.json');
-const capsule2Schema = require('../schema/runtime-capsule-2.schema.json');
+const runtimeCapsuleSchema = require('../schema/runtime-capsule.schema.json');
 
 const SHA256_RE = /^sha256:[0-9a-f]{64}$/;
-const DIGEST_PROFILE = 'kdna-capsule-digests-v1';
-const CAPSULE_DIGEST_PROFILE = 'kdna-capsule-jcs-v1';
+const DIGEST_PROFILE = 'kdna.digest-evidence';
+const DIGEST_PROFILE_VERSION = '0.1.0';
+const CAPSULE_DIGEST_PROFILE = 'kdna.canonicalization.runtime-capsule-jcs';
+const CANONICALIZATION_PROFILE_VERSION = '0.1.0';
+const RUNTIME_CAPSULE_CONTRACT_VERSION = '0.1.0';
 const COMPARISON_SOURCES = new Set([
   'caller',
   'registry',
@@ -23,7 +25,6 @@ const COMPARISON_SOURCES = new Set([
   'kdna.json.content_digest',
   'kdna.json.authoring.content_digest',
   'checksums.json.entry_set_digest',
-  'checksums.json.asset_digest',
 ]);
 const EXTERNAL_COMPARISON_SOURCES = new Set([
   'caller',
@@ -37,32 +38,19 @@ const COMPARISON_TARGETS = new Set([
   'checksum_declaration',
 ]);
 const BASIS = Object.freeze({
-  asset: 'kdna-container-bytes-v1',
-  content: 'kdna-content-tree-v1',
-  runtime_entry_set: 'kdna-runtime-entry-set-v1',
+  asset: 'kdna.digest-basis.container-bytes',
+  content: 'kdna.digest-basis.content-tree',
+  runtime_entry_set: 'kdna.digest-basis.runtime-entry-set',
 });
-const CAPSULE_1_EXTENSION_KEYS = Object.freeze([
-  'extends_chain',
-  'inheritance_applied',
-  'resolved_dependencies',
-  'rag_isolation_policy',
-]);
-const CAPSULE_1_ACCESS_MAP = Object.freeze({
-  open: 'public',
-  protected: 'licensed',
-  runtime: 'remote',
-});
-
 let validators;
 
 function schemaValidators() {
   if (validators) return validators;
-  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  const ajv = new JsonSchema2020({ allErrors: true, strict: false });
   addFormats(ajv);
   ajv.addSchema(digestEvidenceSchema);
   validators = {
-    capsule1: ajv.compile(capsule1Schema),
-    capsule2: ajv.compile(capsule2Schema),
+    runtimeCapsule: ajv.compile(runtimeCapsuleSchema),
   };
   return validators;
 }
@@ -85,8 +73,8 @@ function snapshotPackagedBytes(input) {
   }
   if (typeof input !== 'string') {
     fail(
-      'KDNA_CAPSULE_2_INPUT_INVALID',
-      'Capsule 2 requires a packaged .kdna path, Buffer, or Uint8Array.',
+      'KDNA_RUNTIME_CAPSULE_INPUT_INVALID',
+      'Runtime Capsule requires a packaged .kdna path, Buffer, or Uint8Array.',
     );
   }
 
@@ -94,16 +82,16 @@ function snapshotPackagedBytes(input) {
   try {
     stat = fs.statSync(input);
   } catch (error) {
-    fail('KDNA_CAPSULE_2_INPUT_INVALID', `Cannot read packaged KDNA asset: ${error.message}`);
+    fail('KDNA_RUNTIME_CAPSULE_INPUT_INVALID', `Cannot read packaged KDNA asset: ${error.message}`);
   }
   if (stat.isDirectory()) {
     fail(
       'KDNA_ASSET_FILE_REQUIRED',
-      'Runtime Capsule 2 requires final packaged .kdna bytes; authoring directories are not runtime assets.',
+      'Runtime Capsule requires final packaged .kdna bytes; authoring directories are not runtime assets.',
     );
   }
   if (!stat.isFile()) {
-    fail('KDNA_CAPSULE_2_INPUT_INVALID', 'Capsule 2 input is not a regular file.');
+    fail('KDNA_RUNTIME_CAPSULE_INPUT_INVALID', 'Runtime Capsule input is not a regular file.');
   }
   return { bytes: fs.readFileSync(input), inputKind: 'packaged_file' };
 }
@@ -189,23 +177,12 @@ function declaredContentDigest(manifest) {
 
 function declaredEntrySetDigest(checksums) {
   if (!checksums) return null;
-  const canonical = checksums.entry_set_digest !== undefined
+  return checksums.entry_set_digest !== undefined
     ? normalizeDeclaredDigest(
         checksums.entry_set_digest,
         'checksums.json.entry_set_digest',
       )
     : null;
-  const legacy = checksums.asset_digest !== undefined
-    ? normalizeDeclaredDigest(checksums.asset_digest, 'checksums.json.asset_digest')
-    : null;
-  if (canonical && legacy && canonical.value !== legacy.value) {
-    fail(
-      'KDNA_RUNTIME_ENTRY_SET_DIGEST_DECLARATION_CONFLICT',
-      'checksums.json entry_set_digest conflicts with deprecated asset_digest.',
-      { entry_set_digest: canonical.value, asset_digest: legacy.value },
-    );
-  }
-  return canonical || legacy;
 }
 
 function comparisonWithDeclarationPriority(observed, declared, external, declarationTarget) {
@@ -232,13 +209,13 @@ function computeDigestEvidenceFromBytes(assetBytes, options = {}) {
   const checksums = readJsonEntry(asset, 'checksums.json');
   const assetDigest = computeAssetDigest(bytes);
   const contentDigest = reader.contentDigestSync(asset);
-  const entrySetDigest = v1.computeRuntimeEntrySetDigest(
+  const entrySetDigest = container.computeRuntimeEntrySetDigest(
     asset.readEntry('kdna.json'),
     asset.readEntry('payload.kdnab'),
   );
   const externalExpected = options.expectedDigests || {};
   const expectedAsset = normalizeExpectedDigest(
-    externalExpected.asset ?? options.expectedAssetDigest,
+    externalExpected.asset,
     'caller',
   );
   const externalContent = normalizeExpectedDigest(externalExpected.content, 'caller');
@@ -248,6 +225,7 @@ function computeDigestEvidenceFromBytes(assetBytes, options = {}) {
 
   return {
     profile: DIGEST_PROFILE,
+    profile_version: DIGEST_PROFILE_VERSION,
     asset: {
       value: assetDigest,
       basis: BASIS.asset,
@@ -377,63 +355,42 @@ function assertJsonValue(value, code, label) {
   }
 }
 
-function assertCapsule1Success(capsule, code = 'KDNA_CAPSULE_2_BUILD_INVALID') {
-  assertJsonValue(capsule, code, 'Capsule 1');
-  const validator = schemaValidators().capsule1;
-  if (!validator(capsule)) {
-    fail(code, 'Capsule 1 does not satisfy the frozen schema.', schemaErrorDetails(validator));
-  }
-  if (capsule.trace.schema_valid !== true) {
-    fail(code, 'Capsule 1 schema_valid must be true before building Capsule 2.');
-  }
-  if (capsule.signature.state !== capsule.trace.signature_state) {
-    fail(code, 'Capsule 1 signature state conflicts with its trace.');
-  }
-  if (capsule.profile !== capsule.trace.profile) {
-    fail(code, 'Capsule 1 profile conflicts with its trace.');
-  }
-  if (!['public', 'licensed', 'remote'].includes(capsule2Access(capsule.access))) {
-    fail(code, `Capsule 1 access is not a supported Runtime value: ${capsule.access}.`);
-  }
-}
-
-function assertCapsule2Success(capsule, code = 'KDNA_CAPSULE_ADAPTER_INPUT_INVALID') {
-  assertJsonValue(capsule, code, 'Capsule 2');
-  const validator = schemaValidators().capsule2;
+function assertRuntimeCapsuleSuccess(capsule, code = 'KDNA_RUNTIME_CAPSULE_INVALID') {
+  assertJsonValue(capsule, code, 'Runtime Capsule');
+  const validator = schemaValidators().runtimeCapsule;
   if (!validator(capsule)) {
-    fail(code, 'Capsule 2 does not satisfy the successful Runtime schema.', schemaErrorDetails(validator));
+    fail(
+      code,
+      'Runtime Capsule does not satisfy the current contract.',
+      schemaErrorDetails(validator),
+    );
   }
   assertSuccessfulDigestEvidence(capsule.digests);
   if (capsule.signature.state !== capsule.trace.signature_state) {
-    fail(code, 'Capsule 2 signature state conflicts with its trace.');
+    fail(code, 'Runtime Capsule signature state conflicts with its trace.');
   }
   if (capsule.profile !== capsule.trace.profile) {
-    fail(code, 'Capsule 2 profile conflicts with its trace.');
-  }
-  const capsule1Access = capsule.compatibility?.capsule_1_access;
-  if (capsule1Access && CAPSULE_1_ACCESS_MAP[capsule1Access] !== capsule.access) {
-    fail(
-      code,
-      'Capsule 1 compatibility access does not map to Capsule 2 access.',
-      {
-        capsule_1_access: capsule1Access,
-        expected_capsule_2_access: CAPSULE_1_ACCESS_MAP[capsule1Access],
-        capsule_2_access: capsule.access,
-      },
-    );
+    fail(code, 'Runtime Capsule profile conflicts with its trace.');
   }
 }
 
 function assertSuccessfulDigestEvidence(digests) {
-  if (!digests || digests.profile !== DIGEST_PROFILE) {
-    fail('KDNA_CAPSULE_2_DIGEST_EVIDENCE_INVALID', 'Capsule 2 digest evidence is missing.');
+  if (
+    !digests ||
+    digests.profile !== DIGEST_PROFILE ||
+    digests.profile_version !== DIGEST_PROFILE_VERSION
+  ) {
+    fail(
+      'KDNA_RUNTIME_CAPSULE_DIGEST_EVIDENCE_INVALID',
+      'Runtime Capsule digest evidence is missing or uses the wrong profile coordinate.',
+    );
   }
   for (const name of ['asset', 'content', 'runtime_entry_set']) {
     const item = digests[name];
     if (!item || !SHA256_RE.test(item.value || '') || item.basis !== BASIS[name]) {
       fail(
-        'KDNA_CAPSULE_2_DIGEST_EVIDENCE_INVALID',
-        `Capsule 2 ${name} digest evidence is invalid.`,
+        'KDNA_RUNTIME_CAPSULE_DIGEST_EVIDENCE_INVALID',
+        `Runtime Capsule ${name} digest evidence is invalid.`,
       );
     }
     const comparisonState = item.comparison && item.comparison.state;
@@ -446,8 +403,8 @@ function assertSuccessfulDigestEvidence(digests) {
       fail(
         comparisonState === 'mismatched'
           ? mismatchCodes[name]
-          : 'KDNA_CAPSULE_2_DIGEST_EVIDENCE_INVALID',
-        `Capsule 2 cannot be emitted with ${name} comparison ${comparisonState || 'missing'}.`,
+          : 'KDNA_RUNTIME_CAPSULE_DIGEST_EVIDENCE_INVALID',
+        `Runtime Capsule cannot be emitted with ${name} comparison ${comparisonState || 'missing'}.`,
         { digest: name, evidence: item },
       );
     }
@@ -458,8 +415,8 @@ function assertSuccessfulDigestEvidence(digests) {
         !COMPARISON_SOURCES.has(item.comparison.source))
     ) {
       fail(
-        'KDNA_CAPSULE_2_DIGEST_EVIDENCE_INVALID',
-        `Capsule 2 ${name} matched comparison is internally inconsistent.`,
+        'KDNA_RUNTIME_CAPSULE_DIGEST_EVIDENCE_INVALID',
+        `Runtime Capsule ${name} matched comparison is internally inconsistent.`,
       );
     }
     if (
@@ -469,80 +426,60 @@ function assertSuccessfulDigestEvidence(digests) {
         item.comparison.source !== null)
     ) {
       fail(
-        'KDNA_CAPSULE_2_DIGEST_EVIDENCE_INVALID',
-        `Capsule 2 ${name} not_compared evidence must not claim an expectation.`,
+        'KDNA_RUNTIME_CAPSULE_DIGEST_EVIDENCE_INVALID',
+        `Runtime Capsule ${name} not_compared evidence must not claim an expectation.`,
       );
     }
   }
 }
 
-function capsule2Access(access) {
-  if (!access || access === 'open') return 'public';
-  if (access === 'protected') return 'licensed';
-  if (access === 'runtime') return 'remote';
-  return access;
+function normalizeRuntimeAccess(access) {
+  return access === undefined ? 'public' : access;
 }
 
-function buildCapsuleV2({ capsule1, manifest, digests, inputKind, loadedAt } = {}) {
-  if (!capsule1 || capsule1.type !== 'kdna.context.capsule' || capsule1.version !== '1.0') {
-    fail(
-      'KDNA_CAPSULE_2_BUILD_INVALID',
-      'Capsule 2 builder requires a frozen Capsule 1 projection.',
-    );
+function buildRuntimeCapsule({
+  projection,
+  manifest,
+  digests,
+  signature,
+  inputKind,
+  loadedAt,
+  schemaValid,
+} = {}) {
+  if (!projection || typeof projection !== 'object' || Array.isArray(projection)) {
+    fail('KDNA_RUNTIME_CAPSULE_BUILD_INVALID', 'Runtime Capsule builder requires a projection.');
   }
-  assertCapsule1Success(capsule1);
   if (!manifest || typeof manifest !== 'object') {
-    fail('KDNA_CAPSULE_2_BUILD_INVALID', 'Capsule 2 builder requires the Runtime manifest.');
+    fail('KDNA_RUNTIME_CAPSULE_BUILD_INVALID', 'Runtime Capsule builder requires the manifest.');
   }
   for (const field of ['asset_id', 'asset_uid', 'version', 'judgment_version']) {
     if (typeof manifest[field] !== 'string' || manifest[field].length === 0) {
-      fail('KDNA_CAPSULE_2_BUILD_INVALID', `Runtime manifest ${field} is required.`);
+      fail('KDNA_RUNTIME_CAPSULE_BUILD_INVALID', `Runtime manifest ${field} is required.`);
     }
   }
   if (!['packaged_file', 'packaged_bytes'].includes(inputKind)) {
-    fail('KDNA_CAPSULE_2_BUILD_INVALID', 'Capsule 2 input_kind must identify packaged bytes.');
-  }
-  assertSuccessfulDigestEvidence(digests);
-
-  const expectedDomain = manifest.name || manifest.asset_id;
-  if (capsule1.domain !== expectedDomain) {
-    fail(
-      'KDNA_CAPSULE_2_BUILD_INVALID',
-      'Capsule 1 domain does not match the Runtime manifest identity.',
-      { capsule_1: capsule1.domain, manifest: expectedDomain },
-    );
-  }
-  if (capsule1.judgment_version !== manifest.judgment_version) {
     fail(
-      'KDNA_CAPSULE_2_BUILD_INVALID',
-      'Capsule 1 judgment_version does not match the Runtime manifest.',
-      { capsule_1: capsule1.judgment_version, manifest: manifest.judgment_version },
+      'KDNA_RUNTIME_CAPSULE_BUILD_INVALID',
+      'Runtime Capsule input_kind must identify packaged bytes.',
     );
   }
-  const expectedAccess = manifest.access || 'public';
-  if (capsule1.access !== expectedAccess) {
+  assertSuccessfulDigestEvidence(digests);
+  const timestamp = loadedAt || new Date().toISOString();
+  if (typeof timestamp !== 'string' || Number.isNaN(Date.parse(timestamp))) {
     fail(
-      'KDNA_CAPSULE_2_BUILD_INVALID',
-      'Capsule 1 access does not match the Runtime manifest.',
-      { capsule_1: capsule1.access, manifest: expectedAccess },
+      'KDNA_RUNTIME_CAPSULE_BUILD_INVALID',
+      'Runtime Capsule loaded_at must be an ISO date-time string.',
     );
   }
-  if (capsule1.asset_digest !== digests.runtime_entry_set.value) {
-    fail(
-      'KDNA_CAPSULE_2_BUILD_INVALID',
-      'Capsule 1 asset_digest does not match Runtime entry-set digest E.',
-      { capsule_1: capsule1.asset_digest, runtime_entry_set: digests.runtime_entry_set.value },
-    );
-  }
-
-  const timestamp = loadedAt || capsule1.trace?.loaded_at;
-  if (typeof timestamp !== 'string' || Number.isNaN(Date.parse(timestamp))) {
-    fail('KDNA_CAPSULE_2_BUILD_INVALID', 'Capsule 2 loaded_at must be an ISO date-time string.');
+  const runtimeAccess = normalizeRuntimeAccess(manifest.access);
+  if (!['public', 'licensed', 'remote'].includes(runtimeAccess)) {
+    fail('KDNA_RUNTIME_CAPSULE_BUILD_INVALID', `Unsupported Runtime access: ${runtimeAccess}.`);
   }
+  const signatureEvidence = signature || { state: 'absent' };
 
   const capsule = {
-    type: 'kdna.context.capsule',
-    version: '2.0',
+    type: 'kdna.runtime-capsule',
+    contract_version: RUNTIME_CAPSULE_CONTRACT_VERSION,
     asset: {
       asset_id: manifest.asset_id,
       asset_uid: manifest.asset_uid,
@@ -550,138 +487,42 @@ function buildCapsuleV2({ capsule1, manifest, digests, inputKind, loadedAt } = {
       judgment_version: manifest.judgment_version,
     },
     digests,
-    signature: capsule1.signature,
-    access: capsule2Access(capsule1.access),
-    risk_level: capsule1.risk_level,
-    profile: capsule1.profile,
-    context: capsule1.context,
+    signature: signatureEvidence,
+    access: runtimeAccess,
+    profile: projection.profile,
+    context: projection.content || {},
     trace: {
-      payload_encoding: capsule1.trace?.payload_encoding || 'cbor',
+      payload_encoding: manifest.payload?.encoding || 'cbor',
       loaded_by: 'kdna-core',
       loaded_at: timestamp,
       input_kind: inputKind,
       runtime_eligible: true,
-      schema_valid: capsule1.trace?.schema_valid === true,
-      signature_state: capsule1.trace?.signature_state || capsule1.signature?.state,
-      profile: capsule1.profile,
+      schema_valid: schemaValid === true,
+      signature_state: signatureEvidence.state,
+      profile: projection.profile,
     },
   };
-
-  // Capsule 2 identity is always manifest.asset_id. A distinct legacy name is
-  // carried only so the one-way v2 -> v1 adapter can reproduce the frozen v1
-  // `domain` value. It has no routing or identity authority in Capsule 2.
-  const compatibility = {};
-  if (capsule1.domain && capsule1.domain !== manifest.asset_id) {
-    compatibility.capsule_1_domain = capsule1.domain;
-  }
-  if (CAPSULE_1_ACCESS_MAP[capsule1.access]) {
-    compatibility.capsule_1_access = capsule1.access;
-  }
-  const capsule1Extensions = {};
-  for (const key of CAPSULE_1_EXTENSION_KEYS) {
-    if (Object.prototype.hasOwnProperty.call(capsule1, key)) {
-      capsule1Extensions[key] = capsule1[key];
-    }
-  }
-  if (Object.keys(capsule1Extensions).length > 0) {
-    compatibility.capsule_1_extensions = capsule1Extensions;
-  }
-  if (Object.keys(compatibility).length > 0) {
-    capsule.compatibility = compatibility;
-  }
-
-  assertCapsule2Success(capsule, 'KDNA_CAPSULE_2_BUILD_INVALID');
+  assertRuntimeCapsuleSuccess(capsule, 'KDNA_RUNTIME_CAPSULE_BUILD_INVALID');
   return capsule;
 }
 
-function adaptCapsuleV2ToV1(capsule) {
-  if (!capsule || capsule.type !== 'kdna.context.capsule' || capsule.version !== '2.0') {
-    fail('KDNA_CAPSULE_ADAPTER_INPUT_INVALID', 'The adapter requires a Runtime Capsule 2 value.');
-  }
-  assertCapsule2Success(capsule);
-  const domain = capsule.compatibility?.capsule_1_domain || capsule.asset?.asset_id;
-  if (typeof domain !== 'string' || domain.length === 0) {
-    fail('KDNA_CAPSULE_ADAPTER_INPUT_INVALID', 'Capsule 2 has no Capsule 1 domain mapping.');
-  }
-  const capsule1 = {
-    type: 'kdna.context.capsule',
-    version: '1.0',
-    domain,
-    judgment_version: capsule.asset.judgment_version,
-    asset_digest: capsule.digests.runtime_entry_set.value,
-    signature: capsule.signature,
-    access: capsule.compatibility?.capsule_1_access || capsule.access,
-    risk_level: capsule.risk_level,
-    profile: capsule.profile,
-    context: capsule.context,
-    trace: {
-      payload_encoding: capsule.trace.payload_encoding,
-      loaded_by: capsule.trace.loaded_by,
-      loaded_at: capsule.trace.loaded_at,
-      schema_valid: capsule.trace.schema_valid,
-      signature_state: capsule.trace.signature_state,
-      profile: capsule.trace.profile,
-    },
-  };
-  const capsule1Extensions = capsule.compatibility?.capsule_1_extensions;
-  if (capsule1Extensions) {
-    for (const key of CAPSULE_1_EXTENSION_KEYS) {
-      if (Object.prototype.hasOwnProperty.call(capsule1Extensions, key)) {
-        capsule1[key] = capsule1Extensions[key];
-      }
-    }
-  }
-  assertCapsule1Success(capsule1, 'KDNA_CAPSULE_ADAPTER_OUTPUT_INVALID');
-  return capsule1;
-}
-
-function loadCapsuleV2(input, options = {}) {
-  const { bytes, inputKind } = snapshotPackagedBytes(input);
-  let validation;
-  try {
-    validation = v1.validate(bytes);
-  } catch (error) {
-    fail('KDNA_CAPSULE_2_ASSET_INVALID', error.message);
-  }
-  if (validation.overall_valid !== true) {
-    fail(
-      'KDNA_CAPSULE_2_ASSET_INVALID',
-      `Cannot emit Capsule 2 from an invalid asset: ${validation.problems.join('; ')}`,
-      validation,
-    );
-  }
-
-  const digests = computeDigestEvidenceFromBytes(bytes, {
-    expectedDigests: options.expectedDigests,
-    expectedAssetDigest: options.expectedAssetDigest,
-  });
-  assertSuccessfulDigestEvidence(digests);
-  const reader = createKdnaAssetReader();
-  const asset = reader.openSync(bytes);
-  const manifest = reader.readManifestSync(asset);
-  const capsule1 = v1.loadAuthorized(bytes, {
-    ...options,
-    as: 'json',
-  });
-  return buildCapsuleV2({
-    capsule1,
-    manifest,
-    digests,
-    inputKind,
-    loadedAt: options.loadedAt,
-  });
+function loadRuntimeCapsule(input, options = {}) {
+  snapshotPackagedBytes(input);
+  return container.loadAuthorized(input, { ...options, as: 'json' });
 }
 
 module.exports = {
   BASIS,
   CAPSULE_DIGEST_PROFILE,
+  CANONICALIZATION_PROFILE_VERSION,
   DIGEST_PROFILE,
-  adaptCapsuleV2ToV1,
-  buildCapsuleV2,
+  DIGEST_PROFILE_VERSION,
+  RUNTIME_CAPSULE_CONTRACT_VERSION,
+  buildRuntimeCapsule,
   canonicalizeJcs,
   computeAssetDigest,
   computeCapsuleDeliveryDigest,
   computeDigestEvidence,
-  computeRuntimeEntrySetDigest: v1.computeRuntimeEntrySetDigest,
-  loadCapsuleV2,
+  computeRuntimeEntrySetDigest: container.computeRuntimeEntrySetDigest,
+  loadRuntimeCapsule,
 };