@aikdna/kdna-core 0.17.0 → 0.19.0

package/README.md

@@ -1,138 +1,175 @@
 # @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,
-  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', {
   profile: 'compact',
-  as: 'json'
+  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');
 }
 ```
 
-## Supported Runtime Flow
+Runtime entry points accept final packaged bytes or a packaged file. Authoring
+directories must be packed before they can produce a Runtime Capsule.
+
+`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.
+
+## Stable Runtime contracts
+
+There is one current responsibility chain:
 
 ```text
-.kdna file
+packaged .kdna
 → validate
 → planLoad
-→ loadAuthorized
+→ authorize
 → Runtime Capsule
-→ Agent/runtime context
+→ Consumption Plan
+→ Agent Host request and correlated receipt
+→ Judgment Trace
 ```
 
-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.
+Every KDNA-owned contract uses an explicit compatibility coordinate:
 
-For authoring and test fixtures, `pack()` can turn a local working folder into
-a `.kdna` file before validation:
+| 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` |
 
-```text
-local working folder
-→ pack
-→ .kdna file
-→ validate
-→ planLoad
-→ loadAuthorized
-```
+There is no public adapter between competing Capsule or Host generations.
+Unsupported compatibility coordinates fail closed.
+
+## Digest responsibilities
+
+Core keeps four digest bases separate:
+
+- **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.
+
+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`.
 
-## KDNA Asset Container
+## Consumption and Host execution
 
-A `.kdna` asset contains:
+`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.
 
-- `mimetype`
-- `kdna.json`
-- `payload.kdnab`
-- `checksums.json`
+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.
 
-`validate()` checks:
+`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.
 
-- format
-- manifest schema
-- payload parseability
-- checksum consistency
-- load-profile contract
+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.
 
-`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.
+## Licensed account/device grants
 
-### Account/device external grants
+`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.
 
-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.
+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.
 
-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.
+## Projection profiles
 
-## Load Profiles
+`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.
 
-`loadAuthorized()` supports:
+## Deployer-controlled remote Runtime
 
-- `index`
-- `compact`
-- `scenario`
-- `full`
+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:
+
+```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.17.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,8 @@
     "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": [
         "src/",

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
+    }
+  }
+}