@aikdna/kdna-cli 0.21.1 → 0.22.1

package/README.md

@@ -2,17 +2,17 @@
 
 [![npm](https://img.shields.io/npm/v/@aikdna/kdna-cli)](https://www.npmjs.com/package/@aikdna/kdna-cli) [![CI](https://github.com/aikdna/kdna-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/aikdna/kdna-cli/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
-> **KDNA Ecosystem:** [`kdna`](https://github.com/aikdna/kdna) — the protocol. [KDNAChat](https://github.com/aikdna/kdnachat) — the consumption client. [KDNA Studio](https://github.com/aikdna/kdnastudio) — the authoring tool. [KDNAWork](https://github.com/aikdna/kdnawork) — the workbench. **You are here → kdna-cli** — the toolchain. [Registry](https://github.com/aikdna/kdna-registry) — the catalog.
+> **KDNA Core v1 is the official KDNA judgment-asset format and runtime loading contract.** `.kdna` assets are created, inspected, packed, unpacked, and validated through the **official KDNA toolchain**.
 
-**Role**: kdna-cli is the **runtime control plane** — the official reference implementation for asset validation, loading, installation, comparison, publishing, and agent-facing runtime workflows. It bridges Studio output to Chat/Work consumption.
+**Role**: kdna-cli is the **official KDNA runtime CLI** — the official command-line entry point of the KDNA toolchain for inspecting, validating, packing, unpacking, and loading `.kdna` assets.
 
-**KDNA CLI is the official open-source reference implementation for KDNA verification, loading, installation, comparison, registry access, publishing, and agent-facing runtime workflows.**
+**KDNA CLI is the official CLI entry of the KDNA toolchain — the official command-line surface for `.kdna` asset operations.**
 
-It is the runtime control plane for loading, validating, composing, testing, and governing domain judgment for AI agents.
+Third-party products integrate KDNA through the official SDK, CLI, Loader, or API.
 
-KDNA CLI 是 KDNA 验证、加载、安装、比较、注册表访问、发布和 Agent 运行时工作流的官方开源参考实现，也是 AI Agent 加载、验证、组合、测试和治理领域判断的运行控制平面。
+KDNA CLI 是 KDNA 官方工具链的 CLI 入口,是 `.kdna` 资产操作的官方命令行界面。第三方产品通过官方 SDK、CLI、Loader 或 API 接入 KDNA。
 
-The CLI is how a KDNA domain judgment package becomes usable by agents. It installs KDNA domains, verifies their structure and trust metadata, loads them into agent-readable form, compares judgment paths with and without KDNA, and records traces for audit.
+The CLI is how a `.kdna` judgment asset becomes usable by agents. It inspects, validates, packs, unpacks, and loads KDNA assets, and records traces for audit.
 
 KDNA CLI 让一个领域判断资产真正被 Agent 使用。它负责安装 KDNA、验证结构与信任信息、把 KDNA 转换成 Agent 可加载的形式、对比加载前后的判断路径，并记录可审计的使用痕迹。
 
@@ -161,108 +161,44 @@ and CLI is tracked via cross-language test vectors in the
 
 ## SPEC Compatibility
 
-KDNA CLI follows the canonical KDNA asset structure defined in [`aikdna/kdna`](https://github.com/aikdna/kdna).
+KDNA CLI follows the canonical KDNA Container format defined in [`aikdna/kdna`](https://github.com/aikdna/kdna).
 
-A valid KDNA domain is a `.kdna` asset. The internal tree of that asset may include up to six standard KDNA judgment files:
+A valid KDNA asset is a `.kdna` container with:
+- `kdna.json` — public manifest and metadata (no judgment content)
+- `payload.kdnab` — CBOR-encoded judgment payload
+- `signature.kdsig` — Ed25519 signature
 
-- `KDNA_Core.json`
-- `KDNA_Patterns.json`
-- `KDNA_Scenarios.json`
-- `KDNA_Cases.json`
-- `KDNA_Reasoning.json`
-- `KDNA_Evolution.json`
+The authoring source tree uses standard JSON files (KDNA_Core.json, KDNA_Patterns.json, etc.) for human editing and Git review. These files belong to the source tree only and MUST NOT appear as top-level entries in a distribution `.kdna` asset.
 
-The minimum valid `.kdna` asset requires these internal entries:
-
-- `KDNA_Core.json`
-- `KDNA_Patterns.json`
-
-Each KDNA judgment file must include `meta.version`, `meta.domain`, `meta.created`, `meta.purpose`, and `meta.load_condition`.
-
-Source directories are dev-only authoring workspaces. Public install, inspect, verify, load, compare, publish, and agent-facing commands consume `.kdna` assets or installed asset names, not source directories. To create a trusted `.kdna`, use KDNA Studio or a Studio-compatible compiler that records authoring provenance, Human Lock evidence, compiler metadata, and asset digest.
+To create a trusted `.kdna`, use `kdna-studio migrate <source-dir> --out <file.kdna>` or a Studio-compatible compiler that records authoring provenance, Human Lock evidence, compiler metadata, and asset digest.
 
 ---
 
-## Default Registry
+## Legacy Registry (deprecated)
 
-By default, KDNA CLI uses the official KDNA registry. Registry schema v3 is asset-first: installable entries must publish `asset_url`, `asset_digest`, signature metadata, trust snapshot/timestamp metadata, and revocations. Expired, yanked, revoked, or digest-mismatched assets are rejected. Users may override the registry with `KDNA_REGISTRY_URL`.
+KDNA Core v1 is the **official KDNA judgment-asset format**. KDNA Core v1 does not define a registry, marketplace, or quality-badge system. Assets are loaded by path or by the official CLI, not by registry name.
 
-```bash
-# Use the official registry (default)
-kdna install @aikdna/writing
+The legacy `kdna install <name>` command and the `KDNA_REGISTRY_URL` env var are preserved for backward compatibility with the legacy `kdna-registry` repository (marked as a legacy experiment). New KDNA Core v1 integrations should use the official CLI route:
 
-# Use a custom registry
-export KDNA_REGISTRY_URL="https://my-registry.example.com/domains.json"
-kdna install @myorg/internal
+```bash
+kdna inspect <path>
+kdna validate <path>
+kdna pack <source-dir> <output.kdna>
+kdna unpack <input.kdna> <output-dir>
 ```
 
 ---
 
-## Open Source and Commercial Boundary
-
-KDNA keeps the protocol, schemas, validator, core CLI, benchmark tools, and reference examples open source.
-
-Commercial or hosted layers may include:
-
-- Managed registry services
-- Quality badge review workflows
-- Hosted runtime guard
-- Enterprise private registry
-- Team collaboration in KDNA Studio
-- Licensed/private judgment asset distribution
-
-KDNA supports both open judgment assets and licensed/private judgment assets. Open assets remain the default path for community adoption. Licensed assets still use the `.kdna` extension; protected entries are decrypted only in memory after local license activation.
-
-KDNA 同时支持开放判断资产和授权/私有判断资产。开放资产是社区采用的默认路径；授权资产仍然使用 `.kdna` 后缀，受保护条目只会在本地 license activation 通过后以内存方式解密。
-
----
-
-## Environment Variables
-
-| Variable            | Purpose                                                                     |
-| ------------------- | --------------------------------------------------------------------------- |
-| `KDNA_AGENT`        | Override agent name in trace logs (e.g. `claude_code`, `codex`, `opencode`) |
-| `KDNA_REGISTRY_URL` | Override canonical registry URL                                             |
-| `KDNA_IDENTITY_DIR` | Override identity key directory                                             |
-
-## Exit Codes
-
-| Code | Name                      | Meaning                                            |
-| ---- | ------------------------- | -------------------------------------------------- |
-| 0    | `OK`                      | Success                                            |
-| 1    | `VALIDATION_FAILED`       | Structure or schema validation failed              |
-| 2    | `INPUT_ERROR`             | Invalid input, missing argument, not found         |
-| 3    | `TRUST_FAILED`            | Signature or trust verification failed             |
-| 4    | `JUDGMENT_QUALITY_FAILED` | Judgment governance fields missing or insufficient |
-| 5    | `REGISTRY_ERROR`          | Registry lookup or network error                   |
-| 6    | `PROVIDER_ERROR`          | LLM provider (API key, rate limit) error           |
-| 7    | `POLICY_VIOLATION`        | Publishing or governance policy violation          |
-| 8    | `HUMAN_LOCK_REQUIRED`     | Human lock required but not present                |
-
-## JSON Output
-
-Machine-consumable commands support `--json` for structured output:
-
-```bash
-kdna verify @aikdna/writing --json
-kdna available --json
-kdna doctor --agents --json
-kdna trace --json
-kdna history --json
-kdna license verify --json <file>
-```
+## Official toolchain components
 
-## Product Matrix
+KDNA Core v1 is the **official KDNA judgment-asset format**. `.kdna` assets are created, inspected, protected, loaded, and consumed through the official KDNA toolchain. Third-party products integrate KDNA through the official SDK, CLI, Loader, or API.
 
-| Layer        | Product                 | Responsibility                                                                |
-| ------------ | ----------------------- | ----------------------------------------------------------------------------- |
-| Protocol     | KDNA SPEC               | Define judgment asset format                                                  |
-| Core Library | @aikdna/kdna-core       | load / validate / compose / render                                            |
-| Runtime      | @aikdna/kdna-cli        | install / verify / load / compare / publish existing assets / license / trace |
-| Authoring    | KDNA Studio             | author / lock / compile / export / sign / encrypt                             |
-| Consumption  | KDNAChat                | Load, use, compare                                                            |
-| Governance   | KDNA Governance Console | Approve, release, audit                                                       |
-| Distribution | Registry                | Discover, install, license, distribute                                        |
+| Layer | Component | Responsibility |
+| ------ | -------------------------- | --------------- |
+| Format | KDNA Core | Official KDNA judgment-asset format and runtime loading contract |
+| Core Library | @aikdna/kdna-core | Official loader SDK |
+| Runtime | @aikdna/kdna-cli | Official CLI: inspect, validate, pack, unpack, load |
+| Authoring | KDNA Studio Core | Official authoring kernel |
 
 ## Development
 
@@ -275,9 +211,8 @@ npm test
 
 ## Related
 
-- [@aikdna/kdna-core](https://github.com/aikdna/kdna/tree/main/packages/kdna-core) — Pure logic library
-- [KDNA Registry](https://github.com/aikdna/kdna-registry) — Domain catalog
-- [KDNA SPEC](https://github.com/aikdna/kdna) — Protocol specification
+- [@aikdna/kdna-core](https://github.com/aikdna/kdna/tree/main/packages/kdna-core) — Official loader SDK
+- [KDNA SPEC](https://github.com/aikdna/kdna) — Official KDNA Core format
 - [aikdna.com](https://aikdna.com) — Website
 
 ## License

package/fixtures/v1-minimal/checksums.json

@@ -0,0 +1,6 @@
+{
+  "algorithm": "sha256",
+  "manifest_digest": "sha256:placeholder",
+  "payload_digest": "sha256:placeholder",
+  "asset_digest": "sha256:placeholder"
+}

package/fixtures/v1-minimal/kdna.json

@@ -0,0 +1,42 @@
+{
+  "kdna_version": "1.0",
+  "asset_id": "kdna:example:atomspeak-core",
+  "asset_uid": "urn:uuid:00000000-0000-4000-8000-000000000001",
+  "asset_type": "domain",
+  "title": "Atomspeak Core",
+  "version": "1.0.0",
+  "judgment_version": "1.0.0",
+  "created_at": "2026-06-16T00:00:00Z",
+  "updated_at": "2026-06-16T00:00:00Z",
+  "creator": {
+    "name": "Example Author",
+    "id": "example-author"
+  },
+  "compatibility": {
+    "min_loader_version": "1.0.0",
+    "profile": "judgment-profile-v1"
+  },
+  "payload": {
+    "path": "payload.kdnab",
+    "encoding": "json",
+    "encrypted": false
+  },
+  "summary": "Phase 1 minimal example. The smallest valid KDNA v1 asset.",
+  "language": "en",
+  "license": "Apache-2.0",
+  "keywords": ["example", "minimal", "phase-1"],
+  "lineage": {
+    "type": "original",
+    "fork_of": null,
+    "derived_from": null
+  },
+  "load_contract": {
+    "default_profile": "compact",
+    "profiles": {
+      "index": { "requires_decryption": false, "max_tokens_hint": 200 },
+      "compact": { "requires_decryption": false, "max_tokens_hint": 500 },
+      "scenario": { "requires_decryption": false, "selection": "triggered_sections_only" },
+      "full": { "requires_decryption": false, "intended_for": ["audit", "reference"] }
+    }
+  }
+}

package/fixtures/v1-minimal/mimetype

@@ -0,0 +1 @@
+application/vnd.kdna.asset

package/fixtures/v1-minimal/payload.kdnab

@@ -0,0 +1,31 @@
+{
+  "profile": "judgment-profile-v1",
+  "core": {
+    "highest_question": "What does this minimal example demonstrate?",
+    "axioms": [
+      {
+        "id": "a1",
+        "one_sentence": "The minimal payload is the smallest shape that passes the schema."
+      }
+    ],
+    "boundaries": [],
+    "risk_model": {}
+  },
+  "patterns": [],
+  "scenarios": [],
+  "cases": [],
+  "reasoning": {
+    "self_checks": [],
+    "failure_modes": []
+  },
+  "evolution": {
+    "changelog": [
+      {
+        "version": "1.0.0",
+        "date": "2026-06-16",
+        "changes": "Initial Phase 1 example."
+      }
+    ],
+    "version_notes": []
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-cli",
-  "version": "0.21.1",
+  "version": "0.22.1",
   "description": "KDNA CLI — runtime control plane for verifying, installing, loading, comparing, publishing, and auditing existing .kdna assets.",
   "type": "commonjs",
   "bin": {
@@ -15,25 +15,31 @@
     "skills/",
     "LICENSE",
     "NOTICE",
-    "SECURITY.md"
+    "SECURITY.md",
+    "schema/",
+    "fixtures/"
   ],
   "scripts": {
     "lint": "eslint src/ validators/ tests/",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "test": "node --test tests/v07-commands.test.js tests/v012-commands.test.js tests/asset-store.test.js",
+    "test": "npm run test:v1 && npm run test:smoke",
     "test:integration": "node --test tests/integration.test.js",
-    "test:all": "node --test tests/*.test.js",
+    "test:all": "npm run test:v1 && npm run test:smoke && npm run test:legacy",
+    "test:core-smoke": "node scripts/pretest-smoke.js",
     "release:preflight": "node scripts/release-preflight.js",
-    "pretest": "npm install --ignore-scripts"
+    "test:v1": "node --test tests/v1-global-cli.test.js",
+    "test:smoke": "npm run test:core-smoke",
+    "test:legacy": "node --test tests/v07-commands.test.js tests/v012-commands.test.js tests/asset-store.test.js"
   },
   "keywords": [
     "kdna",
     "kdna-cli",
     "ai-agent",
     "domain-judgment",
-    "judgment-protocol",
-    "cli"
+    "cli",
+    "judgment-asset",
+    "official-toolchain"
   ],
   "license": "Apache-2.0",
   "repository": {
@@ -48,10 +54,10 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aikdna/kdna-core": "^0.8.0"
+    "@aikdna/kdna-core": "^0.9.1"
   },
   "optionalDependencies": {
-    "ajv": "^8.17.1",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "cbor-x": "^1.6.4"
   },

package/schema/checksums.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aikdna/kdna/schema/checksums.schema.json",
+  "title": "KDNA Checksums v1",
+  "description": "Per-entry digests for a .kdna container. Stored as checksums.json at the container root.",
+  "type": "object",
+  "required": ["algorithm"],
+  "additionalProperties": true,
+  "properties": {
+    "algorithm": {
+      "type": "string",
+      "description": "Hash algorithm. Phase 1 uses sha256.",
+      "enum": ["sha256", "sha512", "blake2b-256"]
+    },
+    "manifest_digest": {
+      "type": "string",
+      "description": "Digest of the kdna.json entry.",
+      "pattern": "^[a-z0-9-]+:.+$"
+    },
+    "payload_digest": {
+      "type": "string",
+      "description": "Digest of the payload.kdnab entry.",
+      "pattern": "^[a-z0-9-]+:.+$"
+    },
+    "asset_digest": {
+      "type": "string",
+      "description": "Digest of the whole container (per-entry digests combined deterministically).",
+      "pattern": "^[a-z0-9-]+:.+$"
+    },
+    "entries": {
+      "type": "object",
+      "description": "Per-entry digests, keyed by entry name within the container.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["algorithm", "value"],
+        "properties": {
+          "algorithm": { "type": "string" },
+          "value": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schema/load-contract.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aikdna/kdna/schema/load-contract.schema.json",
+  "title": "KDNA Load Contract",
+  "description": "Manifest block that describes how a loader may read the asset. See docs/core/load-contract.md.",
+  "type": "object",
+  "required": ["default_profile", "profiles"],
+  "additionalProperties": true,
+  "properties": {
+    "default_profile": {
+      "type": "string",
+      "enum": ["index", "compact", "scenario", "full"]
+    },
+    "profiles": {
+      "type": "object",
+      "required": ["index", "compact", "scenario", "full"],
+      "additionalProperties": false,
+      "properties": {
+        "index": { "$ref": "#/$defs/profile" },
+        "compact": { "$ref": "#/$defs/profile" },
+        "scenario": { "$ref": "#/$defs/profile" },
+        "full": { "$ref": "#/$defs/profile" }
+      }
+    }
+  },
+  "$defs": {
+    "profile": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "requires_decryption": { "type": "boolean" },
+        "max_tokens_hint": { "type": "integer", "minimum": 0 },
+        "selection": { "type": "string" },
+        "intended_for": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schema/manifest.schema.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aikdna/kdna/schema/manifest.schema.json",
+  "title": "KDNA Manifest v1",
+  "description": "Schema for kdna.json, the public metadata layer of a .kdna container.",
+  "type": "object",
+  "required": [
+    "kdna_version",
+    "asset_id",
+    "asset_uid",
+    "asset_type",
+    "title",
+    "version",
+    "judgment_version",
+    "created_at",
+    "updated_at",
+    "creator",
+    "compatibility",
+    "payload"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "kdna_version": {
+      "type": "string",
+      "description": "KDNA Core version this manifest conforms to.",
+      "const": "1.0"
+    },
+    "asset_id": {
+      "type": "string",
+      "description": "Human-readable identifier with format namespace prefix (e.g. kdna:example:foo).",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*(:[a-zA-Z0-9_.-]+)+$"
+    },
+    "asset_uid": {
+      "type": "string",
+      "description": "Globally unique identifier. URN form recommended.",
+      "format": "uri"
+    },
+    "asset_type": {
+      "type": "string",
+      "enum": ["domain", "cluster", "tool", "sample", "fixture"],
+      "description": "What kind of asset this is. Container format is the same; the value tells callers how to interpret the payload."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Short, human-readable title."
+    },
+    "version": {
+      "type": "string",
+      "description": "Release version of this .kdna file (semver).",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([+-].+)?$"
+    },
+    "judgment_version": {
+      "type": "string",
+      "description": "Semantic version of the encoded judgment system.",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([+-].+)?$"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the asset was first created (ISO 8601)."
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When this release of the asset was produced (ISO 8601)."
+    },
+    "creator": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "id": { "type": "string" }
+      },
+      "description": "Who produced the asset. Provenance only; not a trust claim."
+    },
+    "compatibility": {
+      "type": "object",
+      "required": ["min_loader_version", "profile"],
+      "additionalProperties": true,
+      "properties": {
+        "min_loader_version": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([+-].+)?$"
+        },
+        "profile": {
+          "type": "string",
+          "description": "Payload profile identifier (e.g. judgment-profile-v1).",
+          "const": "judgment-profile-v1"
+        }
+      }
+    },
+    "payload": {
+      "type": "object",
+      "required": ["path", "encoding", "encrypted"],
+      "additionalProperties": true,
+      "properties": {
+        "path": { "type": "string", "const": "payload.kdnab" },
+        "encoding": { "type": "string", "enum": ["json", "cbor"] },
+        "encrypted": { "type": "boolean" }
+      }
+    },
+    "summary": { "type": "string" },
+    "description": { "type": "string" },
+    "language": { "type": "string" },
+    "languages": { "type": "array", "items": { "type": "string" } },
+    "license": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": {
+            "type": { "type": "string" },
+            "url": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "keywords": { "type": "array", "items": { "type": "string" } },
+    "domain_field": { "type": "array", "items": { "type": "string" } },
+    "lineage": {
+      "type": "object",
+      "description": "Provenance object describing how this asset relates to other assets. Phase 1 keeps this a single object (not an array) to avoid the unstable multi-source shape; future phases may add a separate `sources` or `references` field if multi-parent derivation becomes a real requirement.",
+      "required": ["type"],
+      "additionalProperties": true,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "original",
+            "fork",
+            "adaptation",
+            "translation",
+            "private_variant",
+            "organization_variant",
+            "course_variant"
+          ]
+        },
+        "fork_of": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string" },
+            {
+              "type": "object",
+              "required": ["asset_uid"],
+              "properties": {
+                "asset_uid": { "type": "string" },
+                "version": { "type": "string" }
+              }
+            }
+          ]
+        },
+        "derived_from": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } },
+            {
+              "type": "object",
+              "additionalProperties": true
+            }
+          ]
+        }
+      }
+    },
+    "digests": {
+      "type": "object",
+      "description": "Per-entry digests. Alternative to a separate checksums.json.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["algorithm", "value"],
+        "properties": {
+          "algorithm": { "type": "string" },
+          "value": { "type": "string" }
+        }
+      }
+    },
+    "signatures": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["role", "path", "algorithm"],
+        "properties": {
+          "role": { "type": "string" },
+          "path": { "type": "string" },
+          "algorithm": { "type": "string" },
+          "key_id": { "type": "string" }
+        }
+      }
+    },
+    "encryption": { "type": "object" },
+    "load_contract": { "$ref": "load-contract.schema.json" },
+    "scope": { "type": "object" },
+    "evidence_claims": { "type": "object" }
+  }
+}