@aikdna/kdna-core 0.4.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @aikdna/kdna-core
 
-Pure logic library (zero dependencies) for loading, validating, linting, rendering, and composing KDNA domain cognition packages.
+Core library for loading, validating, linting, rendering, composing, and directly reading KDNA `.kdna` cognition assets. It has zero npm runtime dependencies.
 
 ## Installation
 
@@ -8,10 +8,67 @@ Pure logic library (zero dependencies) for loading, validating, linting, renderi
 npm install @aikdna/kdna-core
 ```
 
-## Usage
+## Preferred public API
+
+Third-party adapters should start with the stable asset-first API. These
+functions accept a `.kdna` file path, bytes, or an already opened asset and do
+not require persistent extraction.
+
+```js
+const {
+  inspectKDNA,
+  validateKDNA,
+  loadKDNA,
+  renderForAgent,
+  verifyAsset,
+  verifyDigest,
+  verifySignature,
+  matchDomain,
+  composeKDNA
+} = require('@aikdna/kdna-core');
+
+const info = await inspectKDNA('./writing.kdna');
+const validation = await validateKDNA('./writing.kdna');
+const loaded = await loadKDNA('./writing.kdna', { profile: 'compact' });
+const promptContext = await renderForAgent('./writing.kdna');
+
+await verifyAsset('./writing.kdna', {
+  asset_digest: info.asset_digest,
+  requireSignature: true
+});
+await verifyDigest('./writing.kdna', info.asset_digest);
+await verifySignature('./writing.kdna');
+
+const matches = await matchDomain('Review this writing draft', ['./writing.kdna']);
+const composed = await composeKDNA(['./writing.kdna', './agent_safety.kdna'], {
+  input: 'Review this public release note for safety and writing quality'
+});
+```
+
+Stable entry points:
+
+| Function | Purpose |
+| --- | --- |
+| `openKDNA()` | Open a `.kdna` file or bytes as an immutable asset. |
+| `inspectKDNA()` | Return manifest, entries, access, quality, risk, and digests. |
+| `validateKDNA()` | Run asset, lint, schema, and cross-file validation. |
+| `loadKDNA()` | Load index/compact/scenario/full profiles directly from `.kdna`. |
+| `renderForAgent()` | Render a loaded asset into agent prompt context. |
+| `verifyAsset()` | Run full asset verification: digest, content digest, signature, and trust metadata. |
+| `verifyDigest()` | Check whole-file `asset_digest`. |
+| `verifySignature()` | Require Ed25519 signature verification. |
+| `matchDomain()` | Rank candidate assets for a task string. |
+| `composeKDNA()` | Compose multiple assets with attribution and conflict reporting. |
+
+## Lower-level usage
 
 ```js
-const { lintDomain, validateDomainSchema, validateCrossFile, renderDomain } = require('@aikdna/kdna-core');
+const {
+  createKdnaAssetReader,
+  lintDomain,
+  validateDomainSchema,
+  validateCrossFile
+} = require('@aikdna/kdna-core');
 
 // Validate a domain
 const dataMap = {
@@ -26,6 +83,65 @@ const crossResult = validateCrossFile(dataMap);
 
 ## API
 
+### `createKdnaAssetReader()`
+
+Direct `.kdna` container reader. The reader opens ZIP-backed `.kdna` assets without persistent extraction and exposes:
+
+- `open(pathOrBytes)`
+- `listEntries(asset)`
+- `readEntry(asset, entryName)`
+- `readJson(asset, entryName)`
+- `readManifest(asset)`
+- `readDataMap(asset)`
+- `contentDigest(asset)`
+- `verify(asset, { asset_digest?, content_digest?, requireSignature? })`
+- `loadProfile(asset, "index" | "compact" | "scenario" | "full", options?)`
+
+Example:
+
+```js
+const { createKdnaAssetReader } = require('@aikdna/kdna-core');
+
+const reader = createKdnaAssetReader();
+const asset = await reader.open('./writing.kdna');
+const manifest = await reader.readManifest(asset);
+const trust = await reader.verify(asset, { requireSignature: true });
+const loaded = await reader.loadProfile(asset, 'compact');
+```
+
+The asset reader treats extraction caches as implementation details. The `.kdna` file remains the identity, install, verification, and loading object.
+
+Licensed assets can list encrypted JSON entries in `kdna.json`:
+
+```json
+{
+  "access": "licensed",
+  "encryption": {
+    "profile": "kdna-licensed-entry-v1",
+    "encrypted_entries": ["KDNA_Core.json", "KDNA_Patterns.json"]
+  }
+}
+```
+
+The reader never writes decrypted entries to disk. Callers provide an in-memory
+`decryptEntry` hook when they have already validated license activation:
+
+```js
+const { createLicensedDecryptEntry } = require('@aikdna/kdna-core');
+
+const decryptEntry = createLicensedDecryptEntry({
+  licenseKey: activation.license_key,
+  machineFingerprint: activation.machine_fingerprint
+});
+
+const loaded = await reader.loadProfile(asset, 'compact', { decryptEntry });
+```
+
+The profile uses AES-256-GCM over each protected entry and derives the entry key
+from the license key plus machine fingerprint using `scrypt-sha256`. This is a
+runtime primitive, not a license activation system; callers must validate license
+status before passing a decrypt hook to the reader.
+
 ### `lintDomain(dataMap)`
 Structural linting — checks required files, field presence, unique IDs, yes/no answerable self-checks, cross-file references, and flags potentially vague axioms.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "KDNA core library — pure logic for loading, validating, linting, and rendering KDNA domain cognition packages. Zero Node.js dependencies.",
   "type": "commonjs",
   "main": "src/index.js",
@@ -16,7 +16,7 @@
   },
   "types": "src/types.d.ts",
   "scripts": {
-    "test": "node -e \"const m = require('./src/index.js'); console.log('kdna-core exports:', Object.keys(m).join(', '));\""
+    "test": "node --test test/*.test.js && node -e \"const m = require('./src/index.js'); console.log('kdna-core exports:', Object.keys(m).join(', '));\""
   },
   "files": [
     "src/",
@@ -32,7 +32,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/aikdna/KDNA.git",
+    "url": "git+https://github.com/aikdna/kdna.git",
     "directory": "packages/kdna-core"
   },
   "homepage": "https://aikdna.com",

package/schema/KDNA_Scenarios.schema.json

@@ -32,7 +32,7 @@
       }
     },
     "scenes": {
-      "description": "Deprecated since v1.0-rc. Use scenarios (canonical) instead. Kept for backward compatibility.",
+      "description": "Not part of KDNA v1.0. Use scenarios.",
       "type": "array",
       "items": {
         "type": "object",
@@ -42,7 +42,7 @@
           "name": { "type": "string" },
           "trigger_signal": {
             "type": "string",
-            "description": "Deprecated since v1.0-rc. Use trigger_signals (array) instead. Kept for backward compatibility."
+            "description": "Not part of KDNA v1.0. Use trigger_signals."
           },
           "trigger_signals": {
             "type": "array",

package/schema/kdna-file.schema.json

@@ -1,14 +1,25 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://aikdna.com/schema/kdna-file.schema.json",
-  "title": "KDNA Single-File Format",
-  "description": "Schema for the .kdna single-file distribution format. Combines all KDNA domain files into one transportable file.",
+  "title": "KDNA Legacy Merged Single-File Format (Rejected)",
+  "description": "Legacy v0.x merged JSON/YAML single-file format. This format is not valid for KDNA v1.0-rc; conforming v1.0 tools MUST reject it and use the ZIP .kdna container with root mimetype and kdna.json.",
   "type": "object",
-  "required": ["kdna_spec", "meta", "core", "patterns"],
+  "not": {},
+  "required": ["format", "format_version", "spec_version", "meta", "core", "patterns"],
   "properties": {
-    "kdna_spec": {
+    "format": {
       "type": "string",
-      "description": "KDNA spec version this file conforms to (e.g., '0.4')."
+      "const": "kdna",
+      "description": "KDNA format marker."
+    },
+    "format_version": {
+      "type": "string",
+      "const": "1.0",
+      "description": "KDNA single-file manifest format version."
+    },
+    "spec_version": {
+      "type": "string",
+      "description": "KDNA spec version this file conforms to."
     },
     "meta": {
       "type": "object",
@@ -23,7 +34,6 @@
         "updated": { "type": "string", "description": "ISO date of last update." },
         "purpose": { "type": "string", "description": "What judgment this domain improves." },
         "description": { "type": "string" },
-        "language": { "type": "string" },
         "languages": { "type": "array", "items": { "type": "string" } }
       },
       "additionalProperties": true

package/schema/kdna-manifest-v1rc.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aikdna.com/schema/kdna-manifest-v1rc.json",
+  "title": "KDNA Domain Manifest (kdna.json)",
+  "description": "Canonical JSON Schema for the kdna.json manifest inside a .kdna asset internal domain tree or dev source workspace. This is the single source of truth: CLI, Registry, Studio, and compatible loaders MUST validate against this schema.",
+
+  "type": "object",
+  "required": [
+    "format",
+    "format_version",
+    "spec_version",
+    "name",
+    "version",
+    "judgment_version",
+    "description",
+    "author",
+    "license",
+    "status",
+    "quality_badge",
+    "access",
+    "languages",
+    "default_language"
+  ],
+  "properties": {
+
+    "format": {
+      "type": "string",
+      "const": "kdna",
+      "description": "KDNA container format marker."
+    },
+
+    "format_version": {
+      "type": "string",
+      "const": "1.0",
+      "description": "KDNA container manifest format version."
+    },
+
+    "spec_version": {
+      "type": "string",
+      "description": "KDNA SPEC version this asset conforms to. Required.",
+      "examples": ["1.0-rc"]
+    },
+
+    "name": {
+      "type": "string",
+      "pattern": "^@[a-z][a-z0-9-]*/[a-z][a-z0-9_]*$",
+      "description": "Scoped domain identifier. Format: @scope/name. scope matches the GitHub org. name uses snake_case.",
+      "examples": ["@aikdna/writing", "@aikdna/agent_safety"]
+    },
+
+    "version": {
+      "type": "string",
+      "description": "Semantic version (MAJOR.MINOR.PATCH) of the domain asset. Tracks packaging and metadata changes. Independent of judgment_version.",
+      "examples": ["0.7.2"]
+    },
+
+    "judgment_version": {
+      "type": "string",
+      "description": "Version of the domain's judgment content (axioms, ontology, misunderstandings). MUST be incremented when any judgment-relevant content changes. Uses YYYY.MM format or semver.",
+      "examples": ["2026.05"]
+    },
+
+    "description": {
+      "type": "string",
+      "minLength": 20,
+      "description": "What judgment this domain improves. One sentence that answers: what does loading this domain change about how an agent thinks?"
+    },
+
+    "core_insight": {
+      "type": "string",
+      "minLength": 10,
+      "description": "Optional. The single most important cognitive shift this domain creates. Used for display in Compare Mode and registry previews."
+    },
+
+    "author": {
+      "type": "object",
+      "required": ["name", "id"],
+      "properties": {
+        "name": { "type": "string", "description": "Author display name." },
+        "id": { "type": "string", "description": "Author identifier (e.g., GitHub handle or email prefix)." },
+        "pubkey": {
+          "type": "string",
+          "pattern": "^ed25519:[0-9a-f]{64}$",
+          "description": "Ed25519 public key for signature verification. Required for signed domains."
+        },
+        "public_key_pem": {
+          "type": "string",
+          "description": "PEM-encoded Ed25519 public key used by verifiers."
+        }
+      }
+    },
+
+    "license": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "License identifier. CC-BY-4.0 for open domains, KCL-1.0 for commercial/pro domains.",
+          "examples": ["CC-BY-4.0", "KCL-1.0", "MIT"]
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to the full license text."
+        }
+      }
+    },
+
+    "status": {
+      "type": "string",
+      "enum": ["draft", "experimental", "stable", "deprecated", "staging"],
+      "description": "Domain maturity level. draft = early work in progress. experimental = complete but not yet proven in practice. stable = structure frozen, content mature. deprecated = superseded by another domain. staging = non-public pre-release (for pro/commercial domains)."
+    },
+
+    "quality_badge": {
+      "type": "string",
+      "enum": ["untested", "tested", "validated", "expert_reviewed", "production_ready"],
+      "description": "Evidence level for judgment quality. untested = schema validation only. tested = >= 10 eval cases with manual verification. validated = >= 30 eval cases with automated scoring and raw outputs. expert_reviewed = validated evidence plus external domain expert review. production_ready = expert_reviewed evidence plus real-world deployment evidence."
+    },
+
+    "access": {
+      "type": "string",
+      "enum": ["open", "licensed", "runtime"],
+      "description": "Distribution mode. open = plaintext, freely available. licensed = encrypted, requires local license. runtime = not distributed, server-side API only."
+    },
+
+    "languages": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "All languages this domain supports (ISO 639-1 codes).",
+      "examples": [["en", "zh-CN"]]
+    },
+
+    "default_language": {
+      "type": "string",
+      "description": "Default language for agent loading when none specified."
+    },
+
+    "i18n_level": {
+      "type": "string",
+      "enum": ["L0", "L1", "L2", "L3"],
+      "description": "Internationalization maturity. L0 = single language only. L1 = basic translation of axioms. L2 = full bilingual (en + zh-CN minimum). L3 = multi-language with locale-aware content."
+    },
+
+    "keywords": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Discovery keywords for search and categorization."
+    },
+
+    "file_count": {
+      "type": "integer",
+      "minimum": 2,
+      "maximum": 6,
+      "description": "Number of standard KDNA JSON entries in the asset internal tree or dev source workspace (excluding kdna.json). Minimum 2 (Core + Patterns). Maximum 6."
+    },
+
+    "risk_level": {
+      "type": "string",
+      "enum": ["R0", "R1", "R2", "R3"],
+      "description": "Risk level for the domain. R0 = low risk (writing style, aesthetics). R1 = medium-low (product decisions, management). R2 = medium (safety, finance, legal). R3 = high (security strategy, code execution). Determines load warnings and certification requirements."
+    },
+
+    "privacy_level": {
+      "type": "string",
+      "enum": ["public", "private", "sensitive", "regulated"],
+      "description": "Privacy classification. Proposed for v1.1; optional in v1.0."
+    },
+
+    "asset_type": {
+      "type": "string",
+      "enum": [
+        "domain_judgment",
+        "personal_judgment",
+        "organization_standard",
+        "team_policy",
+        "creator_style",
+        "risk_guard"
+      ],
+      "description": "Judgment asset category. Proposed for v1.1; optional in v1.0."
+    },
+
+    "fitness_for_purpose": {
+      "type": "object",
+      "description": "Applicability boundary for runtime policy and human review.",
+      "properties": {
+        "intended_use": { "type": "array", "items": { "type": "string" } },
+        "not_for": { "type": "array", "items": { "type": "string" } },
+        "requires_human_review_when": { "type": "array", "items": { "type": "string" } },
+        "known_failure_modes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+
+    "signature": {
+      "type": "string",
+      "pattern": "^ed25519:[0-9a-f]{128}$",
+      "description": "Ed25519 signature over the canonical payload. Required for domains with quality_badge >= tested."
+    },
+
+    "created": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO date of first creation."
+    },
+
+    "updated": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO date of last modification."
+    },
+
+    "replaced_by": {
+      "type": "string",
+      "description": "Required when status is deprecated. The name of the successor domain."
+    }
+  },
+
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "deprecated" } } },
+      "then": { "required": ["replaced_by"] }
+    },
+    {
+      "if": {
+        "properties": {
+          "quality_badge": { "enum": ["tested", "validated", "expert_reviewed", "production_ready"] }
+        }
+      },
+      "then": {
+        "required": ["signature"],
+        "properties": {
+          "author": { "required": ["pubkey"] }
+        }
+      }
+    }
+  ],
+
+  "additionalProperties": false
+}