@aikdna/kdna-core 0.5.0 → 0.7.0

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;