@aikdna/kdna-core 0.5.0 → 0.6.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.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",

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

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(', ')}`);

package/src/index.js

@@ -8,8 +8,10 @@ const render = require('./render');
 const compose = require('./compose');
 const assetReader = require('./asset-reader');
 const cryptoProfile = require('./crypto-profile');
+const publicApi = require('./public-api');
 
 module.exports = {
+  ...publicApi,
   ...loader,
   ...lint,
   ...validate,

package/src/lint-pure.js

@@ -261,11 +261,20 @@ const VALID_BADGE = new Set(['untested', 'tested', 'validated', 'expert_reviewed
 const VALID_ACCESS = new Set(['open', 'licensed', 'runtime']);
 const VALID_RISK = new Set(['R0', 'R1', 'R2', 'R3']);
 const VALID_I18N = new Set(['L0', 'L1', 'L2', 'L3']);
+const VALID_PRIVACY = new Set(['public', 'private', 'sensitive', 'regulated']);
+const VALID_ASSET_TYPE = new Set([
+  'domain_judgment',
+  'personal_judgment',
+  'organization_standard',
+  'team_policy',
+  'creator_style',
+  'risk_guard',
+]);
 
 const MANIFEST_REQUIRED = [
-  'kdna_spec', 'name', 'version', 'judgment_version',
-  'description', 'author', 'license', 'status',
-  'quality_badge', 'access', 'language',
+  'format', 'format_version', 'spec_version', 'name', 'version',
+  'judgment_version', 'description', 'author', 'license', 'status',
+  'quality_badge', 'access', 'languages', 'default_language',
 ];
 
 /**
@@ -283,13 +292,15 @@ function validateManifest(manifest) {
     return { errors, warnings };
   }
 
-  // 1. Check spec_version is NOT in domain manifest (use kdna_spec only)
-  if ('spec_version' in manifest) {
+  // 1. Check disallowed pre-v1.0 manifest aliases
+  if ('kdna_spec' in manifest) {
     errors.push(
-      'kdna.json: spec_version is deprecated in domain manifests. Use kdna_spec. ' +
-      '(spec_version is reserved for .kdna container manifests only.)',
+      'kdna.json: kdna_spec is not allowed. Use spec_version.',
     );
   }
+  if ('language' in manifest) {
+    errors.push('kdna.json: language is not allowed. Use default_language and languages.');
+  }
 
   // 2. Check required fields
   for (const field of MANIFEST_REQUIRED) {
@@ -304,6 +315,14 @@ function validateManifest(manifest) {
   }
 
   // 4. Validate enum fields
+  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.status && !VALID_STATUS.has(manifest.status)) {
     errors.push(
       `kdna.json.status: invalid value "${manifest.status}". ` +
@@ -334,6 +353,18 @@ function validateManifest(manifest) {
       `Valid: ${[...VALID_I18N].join(', ')}`,
     );
   }
+  if (manifest.privacy_level && !VALID_PRIVACY.has(manifest.privacy_level)) {
+    warnings.push(
+      `kdna.json.privacy_level: non-standard value "${manifest.privacy_level}". ` +
+      `Valid: ${[...VALID_PRIVACY].join(', ')}`,
+    );
+  }
+  if (manifest.asset_type && !VALID_ASSET_TYPE.has(manifest.asset_type)) {
+    warnings.push(
+      `kdna.json.asset_type: non-standard value "${manifest.asset_type}". ` +
+      `Valid: ${[...VALID_ASSET_TYPE].join(', ')}`,
+    );
+  }
 
   // 5. Deprecated status must have replaced_by
   if (manifest.status === 'deprecated' && !manifest.replaced_by) {
@@ -362,10 +393,10 @@ function validateManifest(manifest) {
     errors.push('kdna.json.license: missing "type"');
   }
 
-  // 9. Validate kdna_spec value
-  if (manifest.kdna_spec && manifest.kdna_spec !== '1.0-rc') {
+  // 9. Validate spec_version value
+  if (manifest.spec_version && manifest.spec_version !== '1.0-rc') {
     warnings.push(
-      `kdna.json.kdna_spec: non-standard value "${manifest.kdna_spec}". Expected "1.0-rc".`,
+      `kdna.json.spec_version: non-standard value "${manifest.spec_version}". Expected "1.0-rc".`,
     );
   }
 

package/src/public-api.js

@@ -0,0 +1,323 @@
+/**
+ * Stable public API for third-party KDNA integrations.
+ *
+ * Lower-level modules remain exported for advanced runtimes, but external
+ * adapters should prefer these names. They encode the asset-first contract:
+ * callers pass .kdna files or bytes, and no persistent directory extraction is
+ * required.
+ */
+
+const { createKdnaAssetReader } = require('./asset-reader');
+const { lintDomain } = require('./lint-pure');
+const { validateCrossFile, validateDomainSchema } = require('./validate-pure');
+const { formatContext } = require('./loader');
+const {
+  composeContextWithAttribution,
+  detectDomainConflicts,
+  classifySignalsAcrossDomains,
+  generateClusterTrace,
+} = require('./compose');
+
+function readerFrom(options = {}) {
+  return options.reader || createKdnaAssetReader();
+}
+
+function isAsset(value) {
+  return value && typeof value === 'object' && value.entries instanceof Map && typeof value.readEntry === 'function';
+}
+
+async function asAsset(input, options = {}) {
+  if (isAsset(input)) return input;
+  return readerFrom(options).open(input);
+}
+
+function asAssetSync(input, options = {}) {
+  if (isAsset(input)) return input;
+  return readerFrom(options).openSync(input);
+}
+
+async function openKDNA(input, options = {}) {
+  return asAsset(input, options);
+}
+
+function openKDNASync(input, options = {}) {
+  return asAssetSync(input, options);
+}
+
+async function inspectKDNA(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = await asAsset(input, { ...options, reader });
+  const profile = await reader.loadProfile(asset, 'index', options);
+  const verification = options.verify === false ? null : await reader.verify(asset, options);
+  return {
+    name: profile.name,
+    version: profile.version,
+    judgment_version: profile.judgment_version,
+    access: profile.manifest.access || 'open',
+    status: profile.manifest.status || null,
+    quality_badge: profile.manifest.quality_badge || null,
+    risk_level: profile.manifest.risk_level || null,
+    keywords: profile.keywords,
+    entries: profile.entries,
+    asset_digest: profile.asset_digest,
+    content_digest: profile.content_digest,
+    signature_valid: verification ? verification.signature_valid : null,
+    ok: verification ? verification.ok : null,
+    errors: verification ? verification.errors : [],
+    warnings: verification ? verification.warnings : [],
+    manifest: profile.manifest,
+  };
+}
+
+function inspectKDNASync(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = asAssetSync(input, { ...options, reader });
+  const profile = reader.loadProfileSync(asset, 'index', options);
+  const verification = options.verify === false ? null : reader.verifySync(asset, options);
+  return {
+    name: profile.name,
+    version: profile.version,
+    judgment_version: profile.judgment_version,
+    access: profile.manifest.access || 'open',
+    status: profile.manifest.status || null,
+    quality_badge: profile.manifest.quality_badge || null,
+    risk_level: profile.manifest.risk_level || null,
+    keywords: profile.keywords,
+    entries: profile.entries,
+    asset_digest: profile.asset_digest,
+    content_digest: profile.content_digest,
+    signature_valid: verification ? verification.signature_valid : null,
+    ok: verification ? verification.ok : null,
+    errors: verification ? verification.errors : [],
+    warnings: verification ? verification.warnings : [],
+    manifest: profile.manifest,
+  };
+}
+
+async function loadKDNA(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = await asAsset(input, { ...options, reader });
+  return reader.loadProfile(asset, options.profile || 'compact', options);
+}
+
+function loadKDNASync(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = asAssetSync(input, { ...options, reader });
+  return reader.loadProfileSync(asset, options.profile || 'compact', options);
+}
+
+async function validateKDNA(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = await asAsset(input, { ...options, reader });
+  const assetResult = await reader.verify(asset, options);
+  let dataMap = null;
+  let lintResult = { errors: [], warnings: [] };
+  let schemaResult = { errors: [], warnings: [] };
+  let crossFileResult = { errors: [], warnings: [] };
+
+  try {
+    dataMap = await reader.readDataMap(asset, undefined, options);
+    lintResult = lintDomain(dataMap);
+    schemaResult = validateDomainSchema(dataMap, options.schemas || {});
+    crossFileResult = validateCrossFile(dataMap);
+  } catch (e) {
+    lintResult.errors.push(e.message);
+  }
+
+  const errors = [
+    ...assetResult.errors,
+    ...lintResult.errors,
+    ...schemaResult.errors,
+    ...crossFileResult.errors,
+  ];
+  const warnings = [
+    ...assetResult.warnings,
+    ...lintResult.warnings,
+    ...schemaResult.warnings,
+    ...crossFileResult.warnings,
+  ];
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    asset: assetResult,
+    lint: lintResult,
+    schema: schemaResult,
+    cross_file: crossFileResult,
+  };
+}
+
+function validateKDNASync(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = asAssetSync(input, { ...options, reader });
+  const assetResult = reader.verifySync(asset, options);
+  let lintResult = { errors: [], warnings: [] };
+  let schemaResult = { errors: [], warnings: [] };
+  let crossFileResult = { errors: [], warnings: [] };
+
+  try {
+    const dataMap = reader.readDataMapSync(asset, undefined, options);
+    lintResult = lintDomain(dataMap);
+    schemaResult = validateDomainSchema(dataMap, options.schemas || {});
+    crossFileResult = validateCrossFile(dataMap);
+  } catch (e) {
+    lintResult.errors.push(e.message);
+  }
+
+  const errors = [
+    ...assetResult.errors,
+    ...lintResult.errors,
+    ...schemaResult.errors,
+    ...crossFileResult.errors,
+  ];
+  const warnings = [
+    ...assetResult.warnings,
+    ...lintResult.warnings,
+    ...schemaResult.warnings,
+    ...crossFileResult.warnings,
+  ];
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    asset: assetResult,
+    lint: lintResult,
+    schema: schemaResult,
+    cross_file: crossFileResult,
+  };
+}
+
+async function renderForAgent(input, options = {}) {
+  const loaded = await loadKDNA(input, options);
+  if (loaded.context != null) return loaded.context;
+  return loaded.domain ? formatContext(loaded.domain) : '';
+}
+
+function renderForAgentSync(input, options = {}) {
+  const loaded = loadKDNASync(input, options);
+  if (loaded.context != null) return loaded.context;
+  return loaded.domain ? formatContext(loaded.domain) : '';
+}
+
+async function verifyAsset(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = await asAsset(input, { ...options, reader });
+  return reader.verify(asset, options);
+}
+
+function verifyAssetSync(input, options = {}) {
+  const reader = readerFrom(options);
+  const asset = asAssetSync(input, { ...options, reader });
+  return reader.verifySync(asset, options);
+}
+
+async function verifyDigest(input, expectedDigest, options = {}) {
+  return verifyAsset(input, { ...options, asset_digest: expectedDigest });
+}
+
+function verifyDigestSync(input, expectedDigest, options = {}) {
+  return verifyAssetSync(input, { ...options, asset_digest: expectedDigest });
+}
+
+async function verifySignature(input, options = {}) {
+  return verifyAsset(input, { ...options, requireSignature: true });
+}
+
+function verifySignatureSync(input, options = {}) {
+  return verifyAssetSync(input, { ...options, requireSignature: true });
+}
+
+function scoreMatch(input, info) {
+  const haystack = String(input || '').toLowerCase();
+  const terms = [
+    info.name,
+    ...(info.keywords || []),
+    info.manifest?.description,
+    info.manifest?.core_insight,
+  ]
+    .filter(Boolean)
+    .map((v) => String(v).toLowerCase());
+  const matched = terms.filter((term) => term && haystack.includes(term.replace(/^@[^/]+\//, '')));
+  return { score: matched.length, matched };
+}
+
+async function matchDomain(input, candidates, options = {}) {
+  const results = [];
+  for (const candidate of candidates || []) {
+    const info = typeof candidate === 'string' || candidate instanceof Uint8Array || isAsset(candidate)
+      ? await inspectKDNA(candidate, { ...options, verify: false })
+      : candidate;
+    const match = scoreMatch(input, info);
+    if (match.score > 0) results.push({ ...info, score: match.score, matched: match.matched });
+  }
+  return results.sort((a, b) => b.score - a.score || String(a.name).localeCompare(String(b.name)));
+}
+
+function matchDomainSync(input, candidates, options = {}) {
+  const results = [];
+  for (const candidate of candidates || []) {
+    const info = typeof candidate === 'string' || candidate instanceof Uint8Array || isAsset(candidate)
+      ? inspectKDNASync(candidate, { ...options, verify: false })
+      : candidate;
+    const match = scoreMatch(input, info);
+    if (match.score > 0) results.push({ ...info, score: match.score, matched: match.matched });
+  }
+  return results.sort((a, b) => b.score - a.score || String(a.name).localeCompare(String(b.name)));
+}
+
+async function composeKDNA(inputs, options = {}) {
+  const loaded = [];
+  for (const input of inputs || []) {
+    const profile = await loadKDNA(input, { ...options, profile: options.profile || 'compact', context: false });
+    if (profile.domain) {
+      loaded.push({
+        id: profile.manifest.name || profile.domain.core?.meta?.domain,
+        name: profile.manifest.name || profile.domain.core?.meta?.domain,
+        manifest: profile.manifest,
+        ...profile.domain,
+      });
+    }
+  }
+  const { selected, excluded } = classifySignalsAcrossDomains(options.input || '', loaded);
+  const selectedIds = new Set(selected.map((d) => d.id));
+  const activeDomains = options.input ? loaded.filter((d) => selectedIds.has(d.id)) : loaded;
+  const conflicts = detectDomainConflicts(activeDomains);
+  const { context, attributionMap } = composeContextWithAttribution(activeDomains, options);
+  return {
+    domains: loaded,
+    activeDomains,
+    selected,
+    excluded,
+    conflicts,
+    context,
+    attributionMap,
+    trace: generateClusterTrace({
+      input: options.input || '',
+      loadedDomains: loaded,
+      activeDomains,
+      conflicts,
+    }),
+  };
+}
+
+module.exports = {
+  openKDNA,
+  openKDNASync,
+  inspectKDNA,
+  inspectKDNASync,
+  loadKDNA,
+  loadKDNASync,
+  validateKDNA,
+  validateKDNASync,
+  renderForAgent,
+  renderForAgentSync,
+  verifyAsset,
+  verifyAssetSync,
+  verifyDigest,
+  verifyDigestSync,
+  verifySignature,
+  verifySignatureSync,
+  matchDomain,
+  matchDomainSync,
+  composeKDNA,
+};

package/src/types.d.ts

@@ -203,15 +203,18 @@ export interface KDNAFileDataMap {
 }
 
 export interface KDNAManifest {
-  kdna_spec: string;
+  format: 'kdna';
+  format_version: '1.0';
+  spec_version: string;
   name: string;
   version: string;
-  judgment_version?: string;
-  status: 'draft' | 'experimental' | 'stable' | 'deprecated' | 'basic' | 'pro';
+  judgment_version: string;
+  status: 'draft' | 'experimental' | 'stable' | 'deprecated' | 'staging';
+  quality_badge: 'untested' | 'tested' | 'validated' | 'expert_reviewed' | 'production_ready';
   access: 'open' | 'licensed' | 'runtime';
   language?: string;
-  default_language?: string;
-  languages?: string[];
+  default_language: string;
+  languages: string[];
   author: { name: string; id?: string; pubkey?: string; public_key_pem?: string };
   license: { type: string; url?: string };
   description: string;
@@ -413,6 +416,74 @@ export function createLicensedDecryptEntry(options: {
   machineFingerprint: string;
 }): NonNullable<KdnaDecryptOptions['decryptEntry']>;
 
+// Stable public API — preferred entry points for third-party integrations.
+export type KDNAAssetInput = string | Uint8Array | KdnaAsset;
+
+export interface KDNAInspectResult {
+  name: string | null;
+  version: string | null;
+  judgment_version: string | null;
+  access: string;
+  status: string | null;
+  quality_badge: string | null;
+  risk_level: string | null;
+  keywords: string[];
+  entries: string[];
+  asset_digest: string;
+  content_digest: string;
+  signature_valid: boolean | null;
+  ok: boolean | null;
+  errors: string[];
+  warnings: string[];
+  manifest: KDNAManifest;
+}
+
+export interface KDNAValidationReport {
+  ok: boolean;
+  errors: string[];
+  warnings: string[];
+  asset: KdnaAssetVerifyResult;
+  lint: LintResult;
+  schema: ValidationResult;
+  cross_file: ValidationResult;
+}
+
+export interface KDNAMatchResult extends KDNAInspectResult {
+  score: number;
+  matched: string[];
+}
+
+export interface KDNAComposeResult {
+  domains: Array<LoadedDomain & { id?: string; name?: string; manifest?: KDNAManifest }>;
+  activeDomains: Array<LoadedDomain & { id?: string; name?: string; manifest?: KDNAManifest }>;
+  selected: Array<{ id: string; name?: string; role?: string; reason: string }>;
+  excluded: Array<{ id: string; name?: string; role?: string; reason: string }>;
+  conflicts: Array<{ type: string; domains: string[]; description: string }>;
+  context: string;
+  attributionMap: Record<string, any>;
+  trace: Record<string, any>;
+}
+
+export function openKDNA(input: KDNAAssetInput): Promise<KdnaAsset>;
+export function openKDNASync(input: KDNAAssetInput): KdnaAsset;
+export function inspectKDNA(input: KDNAAssetInput, options?: { verify?: boolean } & KdnaDecryptOptions): Promise<KDNAInspectResult>;
+export function inspectKDNASync(input: KDNAAssetInput, options?: { verify?: boolean } & KdnaDecryptOptions): KDNAInspectResult;
+export function loadKDNA(input: KDNAAssetInput, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; input?: string; context?: boolean } & KdnaDecryptOptions): Promise<KdnaAssetIndexProfile | KdnaAssetLoadProfile>;
+export function loadKDNASync(input: KDNAAssetInput, options?: { profile?: 'index' | 'compact' | 'scenario' | 'full' | string; input?: string; context?: boolean } & KdnaDecryptOptions): KdnaAssetIndexProfile | KdnaAssetLoadProfile;
+export function validateKDNA(input: KDNAAssetInput, options?: { schemas?: Record<string, any>; requireSignature?: boolean; requireDecryption?: boolean } & KdnaDecryptOptions): Promise<KDNAValidationReport>;
+export function validateKDNASync(input: KDNAAssetInput, options?: { schemas?: Record<string, any>; requireSignature?: boolean; requireDecryption?: boolean } & KdnaDecryptOptions): KDNAValidationReport;
+export function renderForAgent(input: KDNAAssetInput, options?: { profile?: 'compact' | 'scenario' | 'full' | string; input?: string } & KdnaDecryptOptions): Promise<string>;
+export function renderForAgentSync(input: KDNAAssetInput, options?: { profile?: 'compact' | 'scenario' | 'full' | string; input?: string } & KdnaDecryptOptions): string;
+export function verifyAsset(input: KDNAAssetInput, options?: { asset_digest?: string; content_digest?: string; requireSignature?: boolean; requireDecryption?: boolean } & KdnaDecryptOptions): Promise<KdnaAssetVerifyResult>;
+export function verifyAssetSync(input: KDNAAssetInput, options?: { asset_digest?: string; content_digest?: string; requireSignature?: boolean; requireDecryption?: boolean } & KdnaDecryptOptions): KdnaAssetVerifyResult;
+export function verifyDigest(input: KDNAAssetInput, expectedDigest: string, options?: KdnaDecryptOptions): Promise<KdnaAssetVerifyResult>;
+export function verifyDigestSync(input: KDNAAssetInput, expectedDigest: string, options?: KdnaDecryptOptions): KdnaAssetVerifyResult;
+export function verifySignature(input: KDNAAssetInput, options?: KdnaDecryptOptions): Promise<KdnaAssetVerifyResult>;
+export function verifySignatureSync(input: KDNAAssetInput, options?: KdnaDecryptOptions): KdnaAssetVerifyResult;
+export function matchDomain(input: string, candidates: Array<KDNAAssetInput | KDNAInspectResult>, options?: KdnaDecryptOptions): Promise<KDNAMatchResult[]>;
+export function matchDomainSync(input: string, candidates: Array<KDNAAssetInput | KDNAInspectResult>, options?: KdnaDecryptOptions): KDNAMatchResult[];
+export function composeKDNA(inputs: KDNAAssetInput[], options?: { input?: string; profile?: 'compact' | 'scenario' | 'full' | string; separator?: string } & KdnaDecryptOptions): Promise<KDNAComposeResult>;
+
 // Lint
 export function lintDomain(dataMap: KDNAFileDataMap): LintResult;