@aikdna/kdna-core 0.18.0 → 0.19.0

package/README.md

@@ -1,50 +1,38 @@
 # @aikdna/kdna-core
 
-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.
+Core library for packaged `.kdna` judgment assets. It implements one current
+container contract, authorization planning, integrity evidence, Runtime Capsule
+projection, and the correlated Agent Host execution boundary.
 
-## Installation
+## Install
 
 ```bash
 npm install @aikdna/kdna-core
 ```
 
-If you need full JSON Schema validation through Ajv, also install:
+## Pack, validate, plan, and load
 
-```bash
-npm install ajv ajv-formats
-```
-
-## Public API
-
-Use the package root. Version-qualified entrypoints and API names are not part
-of the public contract.
+Use the package root. Version-qualified entry points and parallel generation
+APIs are not part of the public contract.
 
 ```js
 const {
-  inspect,
+  pack,
   validate,
   planLoad,
   loadAuthorized,
-  loadCapsuleV2,
-  computeDigestEvidence,
-  computeCapsuleDeliveryDigest,
-  adaptCapsuleV2ToV1,
-  pack,
-  unpack,
-  buildChecksums,
 } = require('@aikdna/kdna-core');
 
+pack('./authoring-source', './asset.kdna');
+
 const validation = validate('./asset.kdna');
 if (!validation.overall_valid) {
   throw new Error(validation.problems.join('\n'));
 }
 
 const plan = planLoad('./asset.kdna');
-if (plan.can_load_now !== true) {
-  throw new Error(`Asset is not loadable yet: ${plan.required_action}`);
+if (!plan.can_load_now) {
+  throw new Error(`Asset is not loadable: ${plan.required_action}`);
 }
 
 const capsule = loadAuthorized('./asset.kdna', {
@@ -52,230 +40,136 @@ const capsule = loadAuthorized('./asset.kdna', {
   as: 'json',
 });
 
-if (capsule.type !== 'kdna.context.capsule') {
-  throw new Error('Expected a Runtime Capsule');
+if (
+  capsule.type !== 'kdna.runtime-capsule' ||
+  capsule.contract_version !== '0.1.0'
+) {
+  throw new Error('Unexpected Runtime Capsule contract');
 }
 ```
 
-Capsule 2 is opt-in. It exposes A/C/E under distinct digest members while the
-default Runtime API remains on the frozen Capsule 1 contract:
-
-```js
-const expectedA = {
-  value: 'sha256:<64 lowercase hex>',
-  source: 'install_receipt',
-};
-
-const evidence = computeDigestEvidence('./asset.kdna', {
-  expectedDigests: {
-    asset: expectedA,
-  },
-});
-
-const capsule2 = loadCapsuleV2('./asset.kdna', {
-  profile: 'compact',
-  expectedDigests: {
-    asset: expectedA,
-  },
-});
-
-const deliveryDigest = computeCapsuleDeliveryDigest(capsule2);
-const legacyCapsule = adaptCapsuleV2ToV1(capsule2);
-```
+Runtime entry points accept final packaged bytes or a packaged file. Authoring
+directories must be packed before they can produce a Runtime Capsule.
 
-ConsumptionPlan 1, Agent Host 2, and JudgmentTrace 1 are opt-in APIs in
-`@aikdna/kdna-core@0.18.0`. Plan 1 accepts only Capsule 2 plus Host 2: it has no
-downgrade or legacy adapter. The default Runtime path remains Capsule 1,
-ConsumptionPlan 0.9, and Agent Host 1. The opt-in builders derive
-protocol-owned members, while every verifier receives a non-null trusted Plan
-digest and independently observed capabilities, request, receipt, and delivery
-state as explicit context:
+`compatibility.min_loader_version` is a strict `x.y.z` loader package
+coordinate. `inspect` and `validate` expose it together with
+`loader_version` and `loader_compatible`. Structural validation remains
+separate from loadability: `planLoad` and every load path block a valid asset
+that requires a newer loader with `KDNA_LOADER_VERSION_UNSUPPORTED` before
+projection.
 
-```js
-const {
-  parseExecutionContractJsonV1,
-  buildConsumptionPlanV1,
-  buildAgentHost2RequestV1,
-  buildPreHostBudgetBlockedTraceV1,
-  validatePreHostBudgetBlockedTraceV1,
-  validateAgentHost2ReceiptV1,
-  buildJudgmentTraceV1,
-} = require('@aikdna/kdna-core');
+## Stable Runtime contracts
 
-const plan = buildConsumptionPlanV1({
-  plan_id: 'plan_0123456789abcdef',
-  created_at: new Date().toISOString(),
-  task,
-  asset_ref,
-  projection_profile: 'compact',
-  budget,
-  constraints: { enforce_before_host: true, reject_on_exceed: true },
-  trace_policy: { emit: true, storage: 'session' },
-});
+There is one current responsibility chain:
 
-const executionContext = {
-  plan,
-  trustedPlanDigest: plan.integrity.plan_digest,
-  capabilities: observedHostCapabilities,
-  coreCapsuleVersions: ['2.0', '1.0'],
-};
-const request = buildAgentHost2RequestV1(
-  { request_id: 'host_0123456789abcdef01234567', capsule: capsule2 },
-  executionContext,
-);
-
-// Parse raw Host JSON before object-level Schema/correlation validation.
-const receipt = parseExecutionContractJsonV1(rawReceiptBytes);
-const receiptValidation = validateAgentHost2ReceiptV1(receipt, { request });
-if (!receiptValidation.valid) throw new Error(receiptValidation.code);
-
-const trace = buildJudgmentTraceV1(traceInput, {
-  ...executionContext,
-  request,
-  receipt,
-  trustedDeliveryObservation: 'host_receipt',
-});
+```text
+packaged .kdna
+→ validate
+→ planLoad
+→ authorize
+→ Runtime Capsule
+→ Consumption Plan
+→ Agent Host request and correlated receipt
+→ Judgment Trace
 ```
 
-When no receipt exists, Trace construction requires the caller to state the
-trusted observation explicitly as `not_delivered` or `not_observed`; request
-existence alone is not treated as delivery evidence.
+Every KDNA-owned contract uses an explicit compatibility coordinate:
 
-If Capsule projection succeeded but the exact projection or task character
-count exceeds the Plan budget, `buildAgentHost2RequestV1()` fails closed and
-must not be bypassed. Use the dedicated evidence-only terminal instead:
+| Contract | Identity | Compatibility coordinate |
+| --- | --- | --- |
+| Container manifest | `format_version` | `0.1.0` |
+| Payload profile | `profile` + `profile_version` | `kdna.payload.judgment` + `0.1.0` |
+| Runtime Capsule | `type` + `contract_version` | `kdna.runtime-capsule` + `0.1.0` |
+| Consumption Plan | `type` + `contract_version` | `kdna.consumption-plan` + `0.1.0` |
+| Agent Host | `protocol` + `protocol_version` | `kdna.agent-host` + `0.1.0` |
+| Judgment Trace | `type` + `contract_version` | `kdna.judgment-trace` + `0.1.0` |
 
-```js
-const blockedTrace = buildPreHostBudgetBlockedTraceV1(
-  {
-    trace_id: 'trace_0123456789abcdef',
-    timestamp: new Date().toISOString(),
-    capsule: capsule2,
-  },
-  executionContext,
-);
-
-const blockedValidation = validatePreHostBudgetBlockedTraceV1(blockedTrace, {
-  ...executionContext,
-  capsule: capsule2,
-});
-if (!blockedValidation.valid) throw new Error(blockedValidation.code);
-```
+There is no public adapter between competing Capsule or Host generations.
+Unsupported compatibility coordinates fail closed.
 
-This API returns only a `blocked` / `not_delivered` Trace with a fixed budget
-error. It retains A/C/E, sender P, projection profile, exact character actuals,
-and `exceeded` comparison, but it never exposes an over-budget Host request or
-a request ID. Calling it when neither projection nor task is over budget is an
-error.
-
-`parseExecutionContractJsonV1()` is the raw protocol boundary. It rejects
-duplicate decoded object keys, invalid UTF-8, BOMs, non-scalar Unicode,
-non-finite numbers, trailing input, and non-RFC JSON grammar before an object
-validator runs. Its default limits are 2 MiB and 64 nested containers;
-`maxBytes` and `maxDepth` may only tighten those limits. Error
-`code_unit_offset` details are UTF-16 code-unit indexes, not UTF-8 byte
-offsets. Parsed object validators cannot reconstruct overwritten duplicate
-keys, invalid original bytes, or a stripped BOM, so Host adapters must not use
-plain `JSON.parse()` for untrusted protocol messages.
-
-An A, C, or E mismatch is returned as evidence by `computeDigestEvidence()`
-and blocks `loadCapsuleV2()` with a digest-specific error. The adapter always
-maps E to Capsule 1 `asset_digest`; it never substitutes A or C. Core computes
-E from the raw Runtime manifest and payload bytes even when `checksums.json` is
-absent, in which case E is reported as `not_compared`.
-Internal manifest/checksum declarations are checked before independent
-expected values, so a receipt match cannot conceal a bad declaration or
-conflicting digest alias. The adapter also preserves the four frozen Capsule 1
-inheritance/dependency/RAG extension fields through
-`compatibility.capsule_1_extensions` without giving them Capsule 2 authority.
-It preserves only the legacy access aliases `open`, `protected`, and `runtime`
-through `compatibility.capsule_1_access`; Capsule 2 itself always uses
-`public`, `licensed`, or `remote`. These values must map exactly as
-`open`/`public`, `protected`/`licensed`, and `runtime`/`remote`; the builder and
-adapter reject any mismatched pair. The public builder rejects a Capsule 1 value
-whose domain, judgment version, access, or E does not match the supplied
-manifest and digest evidence.
-
-## Supported Runtime Flow
+## Digest responsibilities
 
-```text
-.kdna file
-→ validate
-→ planLoad
-→ loadAuthorized
-→ Runtime Capsule
-→ Agent/runtime context
-```
+Core keeps four digest bases separate:
 
-The default compact Capsule preserves the asset's scoped judgment context:
-`highest_question`, `worldview`, ordered `value_order`, `judgment_role`,
-applicability-aware axioms, boundaries, self-checks, failure modes, and a
-bounded pattern set. Core copies the three optional scoped fields without
-trimming, reordering, or treating them as facts, policy, or quality evidence.
+- **A** — final packaged container bytes;
+- **C** — the canonical content tree;
+- **E** — the raw `kdna.json` and `payload.kdnab` runtime entry set;
+- **P** — the canonical Runtime Capsule delivered to a Host.
 
-For authoring and test fixtures, `pack()` can turn a local working folder into
-a `.kdna` file before validation:
+Use `computeDigestEvidence()` for A/C/E and
+`computeCapsuleDeliveryDigest()` for P. A grant or registry expectation for A
+must never be compared with E from `checksums.json`.
 
-```text
-local working folder
-→ pack
-→ .kdna file
-→ validate
-→ planLoad
-→ loadAuthorized
-```
+## Consumption and Host execution
 
-## KDNA Asset Container
+`buildConsumptionPlan()` creates the single-asset execution plan and its
+detached integrity digest. `buildAgentHostRequest()` validates the accepted
+Plan digest, observed Host capabilities, Capsule compatibility coordinate,
+task, asset identity, budgets, and P before producing a request.
 
-A `.kdna` asset contains:
+Untrusted Host JSON must enter through `parseRuntimeContractJson()` before
+object validation. It rejects duplicate keys, invalid UTF-8, non-JSON numeric
+values, trailing input, and excessive input before correlation checks run.
 
-- `mimetype`
-- `kdna.json`
-- `payload.kdnab`
-- `checksums.json`
+`buildJudgmentTrace()` records delivery, Host execution, budget, result, and
+error evidence. A correlated receipt proves a technical boundary event; it
+does not prove semantic consumption, behavioral influence, judgment quality,
+or model conformance.
 
-`validate()` checks:
+If the exact projection or task exceeds an enforceable pre-Host budget,
+`buildAgentHostRequest()` fails closed. Use
+`buildPreHostBudgetBlockedTrace()` to retain a terminal evidence record without
+creating a deliverable Host request.
 
-- format
-- manifest schema
-- payload parseability
-- checksum consistency
-- load-profile contract
+## Licensed account/device grants
 
-`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.
+`authorizeExternalKeyGrant()` verifies the issuer signature, time window,
+status, account, device, final packaged asset digest A, and encrypted entry.
+It returns a branded entitlement and an in-memory decrypt hook. A plain object
+such as `{ status: 'active' }` is not authorization.
 
-### Account/device external grants
+Keep device private keys in the platform secret store, dispose the returned
+session after loading, and expose only the Runtime Capsule to Agent-facing
+callers. Account grants never silently fall back to password authorization.
 
-RFC-0019 licensed assets can keep the encrypted container publicly available
-while an issuer grants independent account/device access. `authorizeExternalKeyGrant()`
-verifies the issuer signature, lease, revocation state, account, device, asset
-UID/version/digest, and encrypted entry before returning a branded entitlement
-and in-memory decrypt hook. A plain `{status: "active"}` object is not accepted.
+## Projection profiles
 
-Device private keys belong in the platform SecretStore. The returned session
-must be disposed after loading; Agent-facing callers should receive only the
-Runtime Capsule. Account grants never fall back to the password profile.
+`loadAuthorized()` supports `index`, `compact`, `scenario`, and `full`, with
+`json` or `prompt` output. The requested profile controls the emitted context
+shape; implementations must not label one projection as another.
 
-## Load Profiles
+## Deployer-controlled remote Runtime
 
-`loadAuthorized()` supports:
+Ordinary consumers always receive `needs_runtime` / `connect_runtime` when an
+asset declares `access: "remote"`. A deployer that physically controls the
+server-side packaged asset uses the separate package subpath:
 
-- `index`
-- `compact`
-- `scenario`
-- `full`
+```js
+const {
+  loadRemoteRuntimeAsset,
+} = require('@aikdna/kdna-core/remote-runtime');
+
+const fullCapsule = loadRemoteRuntimeAsset('./deployed-judgment.kdna');
+```
 
-Output formats:
+The function accepts one final packaged file path or packaged byte buffer. It
+validates and plans one immutable byte snapshot, accepts only a single remote
+asset, and returns a full JSON Runtime Capsule for the server's projection
+engine. It does not accept caller-selected access, profile, output, dependency,
+or inheritance options.
 
-- `json`
-- `prompt`
+Possession of the deployed asset is the authorization boundary for this
+server-side API. The API does not authenticate network callers, verify their
+entitlements, make plaintext confidential from the deployer, minimize the
+projection returned to a client, or provide an AIKDNA-hosted service. The
+embedding Runtime must implement those request and disclosure controls and
+must never return the full server-side Capsule to an Agent client.
 
 ## Boundary
 
-KDNA Core is content-neutral. It validates file structure and loadability;
-it does not rank judgment quality or endorse specific assets.
+Core validates technical structure, integrity, authorization, compatibility,
+and observed execution facts. It does not rank judgment quality, endorse an
+asset, or claim that a model understood or followed loaded judgment.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@aikdna/kdna-core",
-    "version": "0.18.0",
+    "version": "0.19.0",
     "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
     "engines": {
         "node": ">=18.0.0"
@@ -14,6 +14,11 @@
             "require": "./src/index.js",
             "types": "./src/types.d.ts"
         },
+        "./remote-runtime": {
+            "import": "./src/remote-runtime.mjs",
+            "require": "./src/remote-runtime.js",
+            "types": "./src/remote-runtime.d.ts"
+        },
         "./package.json": "./package.json",
         "./schema/*": "./schema/*"
     },
@@ -21,7 +26,7 @@
     "scripts": {
         "test": "node ../../scripts/run-node-tests.js test/*.test.js && node -e \"const m = require('./src/index.js'); console.log('kdna-core exports:', Object.keys(m).join(', '));\"",
         "prepublishOnly": "npm run release:check",
-        "release:check": "node scripts/check-release-readiness.js",
+        "release:check": "node ../../scripts/check-post-cutover-naming.mjs && node scripts/check-release-readiness.js",
         "publish:guard": "node scripts/check-publish-duplicate.js"
     },
     "files": [

package/schema/agent-host-capabilities.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aikdna/kdna/specs/agent-host-capabilities.schema.json",
+  "title": "KDNA Agent Host Capabilities",
+  "description": "Orthogonal capabilities observed before Runtime contract execution.",
+  "type": "object",
+  "required": [
+    "type",
+    "protocol_version",
+    "capability_basis",
+    "host_protocols",
+    "capsule_versions",
+    "capsule_digest_profiles",
+    "capsule_digest_profile_versions"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "type": {
+      "const": "kdna.agent-host-capabilities"
+    },
+    "capability_basis": {
+      "enum": ["registered_descriptor", "legacy_assumption"]
+    },
+    "host_protocols": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["kdna.agent-host"]
+      }
+    },
+    "capsule_versions": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["0.1.0"]
+      }
+    },
+    "capsule_digest_profiles": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "const": "kdna.canonicalization.runtime-capsule-jcs"
+      }
+    },
+    "protocol_version": {
+      "const": "0.1.0"
+    },
+    "capsule_digest_profile_versions": {
+      "type": "array",
+      "prefixItems": [
+        {
+          "const": "0.1.0"
+        }
+      ],
+      "items": false,
+      "minItems": 1,
+      "maxItems": 1
+    }
+  }
+}