@aikdna/kdna-core 0.5.0 → 0.7.0

package/README.md

@@ -8,7 +8,59 @@ Core library for loading, validating, linting, rendering, composing, and directl
 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.5.0",
+  "version": "0.7.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",

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,346 @@
+{
+  "$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"]
+    },
+
+    "domain_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Stable semantic domain slug generated by the Studio-compatible authoring pipeline."
+    },
+
+    "registry_name": {
+      "type": "string",
+      "pattern": "^@[a-z][a-z0-9-]*/[a-z][a-z0-9_]*$",
+      "description": "Scoped registry distribution name for this asset."
+    },
+
+    "asset_uid": {
+      "type": "string",
+      "description": "Unique identifier for this exported .kdna asset instance. uuidv7 is recommended."
+    },
+
+    "project_uid": {
+      "type": "string",
+      "description": "Stable identifier for the Studio project that produced this asset. uuidv7 is recommended."
+    },
+
+    "build_id": {
+      "type": "string",
+      "pattern": "^build_[A-Za-z0-9_.:-]+$",
+      "description": "Unique identifier for the Studio compile/export run."
+    },
+
+    "content_digest": {
+      "type": "string",
+      "pattern": "^sha256[-:][0-9a-f]{64}$",
+      "description": "Canonical SHA-256 digest of the internal content tree, excluding self-referential digest and signature fields."
+    },
+
+    "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
+    },
+
+    "authoring": {
+      "type": "object",
+      "description": "Studio-compatible authoring provenance. Required for trusted quality claims.",
+      "required": ["created_by"],
+      "properties": {
+        "created_by": {
+          "type": "string",
+          "enum": [
+            "kdna-studio",
+            "kdna-studio-cli",
+            "kdna-studio-sdk",
+            "third-party-studio-compatible",
+            "manual-dev-source"
+          ]
+        },
+        "authoring_tool": { "type": "string" },
+        "authoring_tool_version": { "type": "string" },
+        "compiler": { "type": "string" },
+        "compiler_version": { "type": "string" },
+        "asset_uid": { "type": "string" },
+        "project_uid": { "type": "string" },
+        "build_id": {
+          "type": "string",
+          "pattern": "^build_[A-Za-z0-9_.:-]+$"
+        },
+        "domain_id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$"
+        },
+        "registry_name": {
+          "type": "string",
+          "pattern": "^@[a-z][a-z0-9-]*/[a-z][a-z0-9_]*$"
+        },
+        "content_digest": {
+          "type": "string",
+          "pattern": "^sha256[-:][0-9a-f]{64}$"
+        },
+        "studio_project_digest": {
+          "type": "string",
+          "pattern": "^sha256[-:][0-9a-f]{64}$"
+        },
+        "human_lock_required": { "type": "boolean" },
+        "human_lock_count": { "type": "integer", "minimum": 0 },
+        "ai_assisted": { "type": "boolean" },
+        "human_confirmed": { "type": "boolean" },
+        "compiled_at": { "type": "string", "format": "date-time" }
+      },
+      "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", "authoring"],
+        "properties": {
+          "author": { "required": ["pubkey"] },
+          "authoring": {
+            "required": [
+              "compiler",
+              "compiler_version",
+              "compiled_at",
+              "human_confirmed",
+              "human_lock_count"
+            ],
+            "properties": {
+              "created_by": {
+                "enum": [
+                  "kdna-studio",
+                  "kdna-studio-cli",
+                  "kdna-studio-sdk",
+                  "third-party-studio-compatible"
+                ]
+              },
+              "human_confirmed": { "const": true },
+              "human_lock_count": { "minimum": 1 }
+            }
+          }
+        }
+      }
+    }
+  ],
+
+  "additionalProperties": false
+}

package/src/asset-reader.js

@@ -22,6 +22,7 @@ const STANDARD_ENTRIES = [
 ];
 
 const JSON_ENTRY_RE = /\.json$/i;
+const KDNA_MEDIA_TYPE = 'application/vnd.aikdna.kdna+zip';
 
 function sha256Hex(buf) {
   return crypto.createHash('sha256').update(buf).digest('hex');
@@ -181,8 +182,10 @@ function buildContentDigest(asset) {
     if (entryName === '.DS_Store' || entryName === 'signature.json') continue;
     const entryBuf = asset.readEntry(entryName);
     let digestBuf = entryBuf;
-    if (entryName === 'kdna.json') {
-      digestBuf = Buffer.from(stableStringify(manifestForDigest(parseJson(entryBuf, entryName))));
+    if (JSON_ENTRY_RE.test(entryName)) {
+      const parsed = parseJson(entryBuf, entryName);
+      const value = entryName === 'kdna.json' ? manifestForDigest(parsed) : parsed;
+      digestBuf = Buffer.from(stableStringify(value));
     }
     parts.push(`${entryName}:${sha256Hex(digestBuf)}`);
   }
@@ -201,16 +204,20 @@ function manifestForSignature(manifest, { stripDigestFields = true } = {}) {
   return copy;
 }
 
+function canonicalJsonEntry(entryName, entryBuf, options = {}) {
+  const parsed = parseJson(entryBuf, entryName);
+  const value = entryName === 'kdna.json' ? manifestForSignature(parsed, options) : parsed;
+  return Buffer.from(stableStringify(value));
+}
+
 function buildSigningPayload(asset, options = {}) {
   const parts = [];
-  for (const entryName of [...asset.entries.keys()].filter((name) => JSON_ENTRY_RE.test(name)).sort()) {
-    if (entryName === 'signature.json') continue;
+  for (const entryName of [...asset.entries.keys()].sort()) {
+    if (entryName === '.DS_Store' || entryName === 'signature.json') continue;
     const entryBuf = asset.readEntry(entryName);
     let payloadBuf = entryBuf;
-    if (entryName === 'kdna.json') {
-      payloadBuf = Buffer.from(
-        JSON.stringify(manifestForSignature(parseJson(entryBuf, entryName), options)),
-      );
+    if (JSON_ENTRY_RE.test(entryName)) {
+      payloadBuf = canonicalJsonEntry(entryName, entryBuf, options);
     }
     parts.push(`${entryName}:${sha256Hex(payloadBuf)}`);
   }
@@ -240,15 +247,7 @@ function verifySignature(asset, manifest, errors, warnings) {
   try {
     const signature = Buffer.from(String(manifest.signature).replace(/^ed25519:/, ''), 'hex');
     const publicKey = crypto.createPublicKey(manifest.author.public_key_pem);
-    let ok = crypto.verify(null, Buffer.from(buildSigningPayload(asset)), publicKey, signature);
-    if (!ok) {
-      ok = crypto.verify(
-        null,
-        Buffer.from(buildSigningPayload(asset, { stripDigestFields: false })),
-        publicKey,
-        signature,
-      );
-    }
+    const ok = crypto.verify(null, Buffer.from(buildSigningPayload(asset)), publicKey, signature);
     if (!ok) errors.push('Ed25519 signature invalid');
     return ok;
   } catch (e) {
@@ -257,6 +256,37 @@ function verifySignature(asset, manifest, errors, warnings) {
   }
 }
 
+function verifyMediaType(asset, errors) {
+  if (!asset.entries.has('mimetype')) {
+    errors.push('required entry missing: mimetype');
+    return;
+  }
+  const value = asset.readEntry('mimetype').toString('utf8');
+  if (value !== KDNA_MEDIA_TYPE) {
+    errors.push(`mimetype: expected ${KDNA_MEDIA_TYPE}, got ${JSON.stringify(value)}`);
+  }
+}
+
+function validateManifestIdentity(manifest, errors, _warnings) {
+  if (manifest.kdna_spec) {
+    errors.push('kdna.json: kdna_spec is not allowed. Use spec_version.');
+  }
+  if (manifest.format && manifest.format !== 'kdna') {
+    errors.push(`kdna.json.format: invalid value "${manifest.format}". Expected "kdna".`);
+  }
+  if (manifest.format_version && manifest.format_version !== '1.0') {
+    errors.push(
+      `kdna.json.format_version: invalid value "${manifest.format_version}". Expected "1.0".`,
+    );
+  }
+  if (!manifest.spec_version) errors.push('kdna.json: missing required field "spec_version"');
+  if (!manifest.format) errors.push('kdna.json: missing required field "format"');
+  if (!manifest.format_version) errors.push('kdna.json: missing required field "format_version"');
+  if (manifest.language) {
+    errors.push('kdna.json: language is not allowed. Use default_language and languages.');
+  }
+}
+
 function openAsset(input) {
   const { buffer, path } = normalizeInput(input);
   const entries = parseZipEntries(buffer);
@@ -307,6 +337,7 @@ function verifySync(asset, options = {}) {
   const entries = listEntries(asset);
 
   if (!asset.entries.has('kdna.json')) errors.push('required entry missing: kdna.json');
+  verifyMediaType(asset, errors);
   if (!asset.entries.has('KDNA_Core.json')) errors.push('required entry missing: KDNA_Core.json');
   if (!asset.entries.has('KDNA_Patterns.json')) {
     errors.push('required entry missing: KDNA_Patterns.json');
@@ -326,6 +357,7 @@ function verifySync(asset, options = {}) {
   if (asset.entries.has('kdna.json')) {
     try {
       manifest = readManifest(asset);
+      validateManifestIdentity(manifest, errors, warnings);
       const encrypted = encryptedEntries(manifest);
       if (encrypted.length) {
         warnings.push(`encrypted entries present: ${encrypted.join(', ')}`);
@@ -480,6 +512,7 @@ function createKdnaAssetReader() {
       const entries = [...asset.entries.keys()].sort();
 
       if (!asset.entries.has('kdna.json')) errors.push('required entry missing: kdna.json');
+      verifyMediaType(asset, errors);
       if (!asset.entries.has('KDNA_Core.json')) errors.push('required entry missing: KDNA_Core.json');
       if (!asset.entries.has('KDNA_Patterns.json')) {
         errors.push('required entry missing: KDNA_Patterns.json');
@@ -501,6 +534,7 @@ function createKdnaAssetReader() {
       if (asset.entries.has('kdna.json')) {
         try {
           manifest = parseJson(asset.readEntry('kdna.json'), 'kdna.json');
+          validateManifestIdentity(manifest, errors, warnings);
           const encrypted = encryptedEntries(manifest);
           if (encrypted.length) {
             warnings.push(`encrypted entries present: ${encrypted.join(', ')}`);