@aikdna/kdna-core 0.7.2 → 0.9.0

package/src/workpack-pure.js

@@ -0,0 +1,254 @@
+/**
+ * @aikdna/kdna-core — Work Pack validation (pure logic)
+ *
+ * Zero-dependency pure functions for validating KDNA Work Pack
+ * manifests against the Work Pack schema. Does not depend on ajv
+ * at source level — the validator is injected.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── Embedded Work Pack Schema v0.1 ──────────────────────────────────
+// Self-contained schema with resolved $refs for zero-dependency validation.
+
+const WORK_PACK_SCHEMA = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  $id: 'https://aikdna.com/schemas/work-pack.schema.json',
+  title: 'KDNA Work Pack Manifest',
+  type: 'object',
+  required: ['format', 'format_version', 'name', 'version', 'description', 'status', 'kdna'],
+  properties: {
+    format: { type: 'string', const: 'kdna-workpack' },
+    format_version: { type: 'string', pattern: '^\\d+\\.\\d+$' },
+    name: { type: 'string', pattern: '^[a-z0-9]+(-[a-z0-9]+)*$', maxLength: 64 },
+    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?(\\+[a-zA-Z0-9.]+)?$' },
+    description: { type: 'string', maxLength: 280 },
+    status: { type: 'string', enum: ['draft', 'experimental', 'stable', 'deprecated'] },
+    access: { type: 'string', enum: ['open', 'licensed', 'runtime', 'enterprise', 'partner'], default: 'open' },
+    license: { type: 'string', default: 'Apache-2.0' },
+    kdna: {
+      type: 'object',
+      oneOf: [
+        {
+          required: ['mode', 'asset'],
+          properties: {
+            mode: { const: 'single' },
+            asset: {
+              type: 'object',
+              required: ['name', 'version', 'role'],
+              properties: {
+                name: { type: 'string', pattern: '^[a-z0-9_]+$' },
+                version: { type: 'string' },
+                digest: { type: 'string', pattern: '^sha256:[a-f0-9]{64}$' },
+                role: { type: 'string', enum: ['primary', 'constraint', 'fallback'] },
+              },
+              additionalProperties: false,
+            },
+          },
+        },
+        {
+          required: ['mode', 'assets'],
+          properties: {
+            mode: { const: 'cluster' },
+            assets: {
+              type: 'array',
+              minItems: 2,
+              items: {
+                type: 'object',
+                required: ['name', 'version', 'role'],
+                properties: {
+                  name: { type: 'string', pattern: '^[a-z0-9_]+$' },
+                  version: { type: 'string' },
+                  digest: { type: 'string', pattern: '^sha256:[a-f0-9]{64}$' },
+                  role: { type: 'string', enum: ['primary', 'constraint', 'fallback'] },
+                },
+                additionalProperties: false,
+              },
+            },
+          },
+        },
+      ],
+    },
+    skills: {
+      type: 'array',
+      default: [],
+      items: {
+        type: 'object',
+        required: ['name'],
+        properties: {
+          name: { type: 'string', pattern: '^[a-z0-9]+([_-][a-z0-9]+)*$', maxLength: 64 },
+          type: { type: 'string' },
+          required: { type: 'boolean', default: true },
+          mcp_server: { type: ['string', 'null'], default: null },
+          fallback: { type: ['string', 'null'], default: null },
+        },
+        additionalProperties: false,
+      },
+    },
+    templates: {
+      type: 'object',
+      default: {},
+      properties: {
+        task: { type: 'string' },
+        output: { type: 'string' },
+      },
+    },
+    review_gates: {
+      type: 'array',
+      default: [],
+      items: { type: 'string' },
+    },
+    risk_policy: { type: 'string' },
+    trace_policy: { type: 'string' },
+    evals: { type: 'string' },
+  },
+  additionalProperties: false,
+};
+
+// ── Public API ─────────────────────────────────────────────────────
+
+/**
+ * Validate a Work Pack manifest against the schema.
+ *
+ * @param {object} manifest — parsed workpack.json content
+ * @param {object} [opts]
+ * @param {object} [opts.ajv] — optional pre-configured Ajv instance
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateWorkPackManifest(manifest, opts = {}) {
+  const Ajv = opts.ajv || _lazyAjv();
+  let validate;
+  try {
+    validate = Ajv.compile(WORK_PACK_SCHEMA);
+  } catch (e) {
+    return { valid: false, errors: [`Schema compilation error: ${e.message}`] };
+  }
+  const ok = validate(manifest);
+  if (ok) return { valid: true, errors: [] };
+  const errors = (validate.errors || []).map(
+    (e) => `${e.instancePath || '/'}: ${e.message}`
+  );
+  return { valid: false, errors };
+}
+
+/**
+ * Check structural completeness — verify all referenced files exist.
+ *
+ * @param {object} manifest — parsed workpack.json
+ * @param {string} rootDir — directory containing workpack.json
+ * @returns {{ complete: boolean, missing: string[] }}
+ */
+function checkWorkPackStructure(manifest, rootDir) {
+  const missing = [];
+  const refs = [];
+
+  if (manifest.templates) {
+    if (manifest.templates.task) refs.push(manifest.templates.task);
+    if (manifest.templates.output) refs.push(manifest.templates.output);
+  }
+  if (manifest.review_gates) refs.push(...manifest.review_gates);
+  if (manifest.risk_policy) refs.push(manifest.risk_policy);
+  if (manifest.trace_policy) refs.push(manifest.trace_policy);
+  if (manifest.evals) refs.push(manifest.evals);
+
+  for (const ref of refs) {
+    const fullPath = path.resolve(rootDir, ref);
+    if (!fs.existsSync(fullPath)) missing.push(ref);
+  }
+
+  return { complete: missing.length === 0, missing };
+}
+
+/**
+ * Inspect a Work Pack — return a structured summary.
+ *
+ * @param {object} manifest — parsed workpack.json
+ * @param {string} rootDir — directory containing workpack.json
+ * @returns {object}
+ */
+function inspectWorkPack(manifest, rootDir) {
+  const kdnaMode = manifest.kdna?.mode || 'unknown';
+  const kdnaCount =
+    kdnaMode === 'single' ? 1 : (manifest.kdna?.assets || []).length;
+
+  const structure = checkWorkPackStructure(manifest, rootDir);
+
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    description: manifest.description,
+    status: manifest.status,
+    access: manifest.access || 'open',
+    license: manifest.license || 'Apache-2.0',
+    format_version: manifest.format_version,
+    kdna: {
+      mode: kdnaMode,
+      assets: kdnaMode === 'single'
+        ? [{ name: manifest.kdna.asset.name, version: manifest.kdna.asset.version, role: manifest.kdna.asset.role }]
+        : (manifest.kdna?.assets || []).map(a => ({ name: a.name, version: a.version, role: a.role })),
+    },
+    skills: (manifest.skills || []).map(s => ({
+      name: s.name,
+      type: s.type || 'unspecified',
+      required: s.required !== false,
+      fallback: s.fallback || null,
+    })),
+    templates: manifest.templates
+      ? { task: manifest.templates.task || null, output: manifest.templates.output || null }
+      : null,
+    review_gates: (manifest.review_gates || []).length,
+    has_risk_policy: !!manifest.risk_policy,
+    has_trace_policy: !!manifest.trace_policy,
+    has_evals: !!manifest.evals,
+    structural_complete: structure.complete,
+    missing_files: structure.missing,
+  };
+}
+
+/**
+ * Load a Work Pack from a directory.
+ *
+ * @param {string} dirPath — path to Work Pack directory
+ * @returns {{ manifest: object|null, error: string|null }}
+ */
+function loadWorkPack(dirPath) {
+  const wpPath = path.join(dirPath, 'workpack.json');
+  if (!fs.existsSync(wpPath)) {
+    return { manifest: null, error: `workpack.json not found in ${dirPath}` };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(wpPath, 'utf8'));
+  } catch (e) {
+    return { manifest: null, error: `Invalid JSON in workpack.json: ${e.message}` };
+  }
+  return { manifest, error: null };
+}
+
+// ── Internal ────────────────────────────────────────────────────────
+
+let _ajvInstance = null;
+
+function _lazyAjv() {
+  if (_ajvInstance) return _ajvInstance;
+  try {
+    const Ajv = require('ajv');
+    const addFormats = require('ajv-formats');
+    _ajvInstance = new Ajv({ allErrors: true, strict: false });
+    addFormats(_ajvInstance);
+    return _ajvInstance;
+  } catch (e) {
+    throw new Error(
+      'ajv is required for Work Pack validation. Install: npm install ajv ajv-formats'
+    );
+  }
+}
+
+module.exports = {
+  WORK_PACK_SCHEMA,
+  validateWorkPackManifest,
+  checkWorkPackStructure,
+  inspectWorkPack,
+  loadWorkPack,
+};

package/schema/Composition_Policy.schema.json

@@ -1,130 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "KDNA Composition Policy",
-  "description": "Schema for composition.policy.json — defines runtime composition behavior for domain clusters.",
-  "type": "object",
-  "required": ["policy_id", "version"],
-  "properties": {
-    "policy_id": {
-      "type": "string",
-      "description": "Unique policy identifier"
-    },
-    "version": {
-      "type": "string",
-      "description": "Semantic version of this policy"
-    },
-    "selection_policy": {
-      "type": "object",
-      "properties": {
-        "mode": {
-          "type": "string",
-          "enum": ["signal_based", "fixed", "staged", "overlay", "user_confirmed"]
-        },
-        "max_domains": { "type": "integer", "minimum": 1 },
-        "min_signal_score": { "type": "number", "minimum": 0, "maximum": 1 },
-        "ask_user_when_ambiguous": { "type": "boolean" }
-      }
-    },
-    "priority_policy": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["when", "domain", "priority", "effect"],
-        "properties": {
-          "when": { "type": "string", "description": "Condition expression triggering this rule" },
-          "domain": { "type": "string", "description": "Domain ID" },
-          "priority": { "type": "integer", "minimum": 0, "maximum": 100 },
-          "effect": {
-            "type": "string",
-            "enum": ["must_include", "block_or_require_confirmation", "deprioritize", "override"]
-          }
-        }
-      }
-    },
-    "conflict_policy": {
-      "type": "object",
-      "properties": {
-        "default": {
-          "type": "string",
-          "enum": ["surface", "priority_wins", "risk_wins", "block", "ask_user", "allow_with_warning"]
-        },
-        "rules": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": ["conflict_type", "action"],
-            "properties": {
-              "conflict_type": {
-                "type": "string",
-                "enum": ["value_conflict", "term_conflict", "risk_conflict", "stance_conflict", "framework_conflict", "output_policy_conflict", "priority_conflict"]
-              },
-              "action": {
-                "type": "string",
-                "enum": ["surface", "surface_and_ask", "risk_wins", "priority_wins", "block", "allow_with_warning"]
-              }
-            }
-          }
-        }
-      }
-    },
-    "merge_policy": {
-      "type": "object",
-      "properties": {
-        "axioms": { "type": "string", "enum": ["include_all_with_source", "dedupe_by_id", "select_by_priority"] },
-        "banned_terms": { "type": "string", "enum": ["union_with_source", "strictest_only", "priority_domain_only"] },
-        "self_checks": { "type": "string", "enum": ["dedupe_by_semantic_similarity", "include_all_with_source", "priority_domain_only"] },
-        "frameworks": { "type": "string", "enum": ["select_by_scenario", "include_all_with_source", "priority_domain_only"] },
-        "stances": { "type": "string", "enum": ["include_conflicts", "priority_domain_only", "merge_with_source"] }
-      }
-    },
-    "output_policy": {
-      "type": "object",
-      "properties": {
-        "must_show_loaded_domains": { "type": "boolean" },
-        "must_record_judgment_trace": { "type": "boolean" },
-        "must_surface_conflicts": { "type": "boolean" },
-        "must_include_uncertainty": { "type": "boolean" }
-      }
-    },
-    "governance": {
-      "type": "object",
-      "properties": {
-        "ownership": {
-          "type": "object",
-          "properties": {
-            "owner_team": { "type": "string" },
-            "maintainers": { "type": "array", "items": { "type": "string" } },
-            "approvers": { "type": "array", "items": { "type": "string" } },
-            "review_cycle": { "type": "string" }
-          }
-        },
-        "lifecycle": {
-          "type": "object",
-          "properties": {
-            "status": { "type": "string", "enum": ["draft", "review", "approved", "active", "deprecated", "archived"] },
-            "effective_from": { "type": "string" },
-            "expires_at": { "type": "string" },
-            "review_required_before": { "type": "string" }
-          }
-        },
-        "change_control": {
-          "type": "object",
-          "properties": {
-            "requires_approval_for": { "type": "array", "items": { "type": "string" } },
-            "minor_changes_allowed_for": { "type": "array", "items": { "type": "string" } },
-            "audit_log_required": { "type": "boolean" }
-          }
-        },
-        "deployment": {
-          "type": "object",
-          "properties": {
-            "environments": { "type": "array", "items": { "type": "string" } },
-            "active_version": { "type": "string" },
-            "rollout_strategy": { "type": "string", "enum": ["manual", "canary", "all_at_once"] },
-            "rollback_version": { "type": "string" }
-          }
-        }
-      }
-    }
-  }
-}

package/schema/KDNA_Cases.schema.json

@@ -1,77 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "KDNA_Cases",
-  "type": "object",
-  "required": [
-    "meta",
-    "cases"
-  ],
-  "properties": {
-    "meta": {
-      "type": "object",
-      "required": [
-        "version",
-        "domain",
-        "created",
-        "purpose",
-        "load_condition"
-      ],
-      "properties": {
-        "version": { "type": "string" },
-        "domain": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
-        "created": { "type": "string" },
-        "purpose": { "type": "string" },
-        "load_condition": { "type": "string" }
-      },
-      "additionalProperties": true
-    },
-    "cases": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id", "title"],
-        "properties": {
-          "id": { "type": "string" },
-          "scene_id": { "type": "string" },
-          "title": { "type": "string" },
-          "context": { "type": "string" },
-          "what_happened": { "type": "string" },
-          "what_was_learned": { "type": "string" },
-          "structural_pattern": { "type": "string" },
-          "narrative": { "type": "string" },
-          "outcome": { "type": "string" },
-          "kdna_analysis": { "type": "string" },
-          "modern_parallel": { "type": "string" },
-          "axiom": { "type": "string" },
-          "judgment_path": {
-            "type": "string",
-            "description": "The judgment process applied in this case."
-          },
-          "good_response": {
-            "type": "string",
-            "description": "An example of a good judgment response."
-          },
-          "bad_response": {
-            "type": "string",
-            "description": "An example of a poor judgment response."
-          },
-          "why_good": {
-            "type": "string",
-            "description": "Why the good response aligns with domain judgment."
-          },
-          "why_bad": {
-            "type": "string",
-            "description": "Why the bad response violates domain judgment."
-          },
-          "triggered_axioms": {
-            "type": "array",
-            "items": { "type": "string" },
-            "description": "Axioms triggered by this case."
-          }
-        },
-        "additionalProperties": true
-      }
-    }
-  },
-  "additionalProperties": true
-}

package/schema/KDNA_Cluster.schema.json

@@ -1,132 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "KDNA Cluster Manifest",
-  "description": "Schema for kdna.cluster.json — defines a composable judgment system of KDNA domains.",
-  "type": "object",
-  "required": ["cluster_id", "name", "version", "domains", "composition"],
-  "properties": {
-    "cluster_id": {
-      "type": "string",
-      "description": "Fully qualified cluster identifier, e.g., @company/product-launch-system"
-    },
-    "name": {
-      "type": "string",
-      "description": "Human-readable cluster name"
-    },
-    "version": {
-      "type": "string",
-      "description": "Semantic version of this cluster manifest"
-    },
-    "description": {
-      "type": "string",
-      "description": "What judgment system this cluster provides"
-    },
-    "type": {
-      "type": "string",
-      "enum": ["horizontal", "vertical", "governance", "enterprise_system"],
-      "description": "Cluster type determining default loading strategy"
-    },
-    "status": {
-      "type": "string",
-      "enum": ["draft", "experimental", "stable", "deprecated"]
-    },
-    "access": {
-      "type": "string",
-      "enum": ["open", "licensed", "runtime"]
-    },
-    "domains": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id", "version", "role", "required", "load_condition"],
-        "properties": {
-          "id": {
-            "type": "string",
-            "description": "Fully qualified domain name (@scope/name)"
-          },
-          "version": {
-            "type": "string",
-            "description": "Semver range, e.g., ^1.2.0"
-          },
-          "role": {
-            "type": "string",
-            "enum": ["primary", "advisor", "risk_guard", "style_and_trust", "evaluator"]
-          },
-          "required": {
-            "type": "boolean",
-            "description": "Whether this domain must load for cluster to function"
-          },
-          "load_condition": {
-            "type": "string",
-            "description": "When this domain should activate"
-          }
-        }
-      }
-    },
-    "relationships": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["from", "to", "type"],
-        "properties": {
-          "from": { "type": "string" },
-          "to": { "type": "string" },
-          "type": {
-            "type": "string",
-            "enum": ["depends_on", "constrains", "overrides", "blocks", "informs", "extends", "refines", "conflicts_with", "evaluates", "expressed_through"]
-          },
-          "description": { "type": "string" }
-        }
-      }
-    },
-    "composition": {
-      "type": "object",
-      "required": ["strategy", "conflict_policy", "priority_order"],
-      "properties": {
-        "strategy": {
-          "type": "string",
-          "enum": ["fixed", "signal_based", "staged", "overlay", "user_confirmed"]
-        },
-        "max_active_domains": {
-          "type": "integer",
-          "minimum": 1
-        },
-        "default_domains": {
-          "type": "array",
-          "items": { "type": "string" }
-        },
-        "conflict_policy": {
-          "type": "string",
-          "enum": ["surface", "priority", "block", "ask_user"]
-        },
-        "priority_order": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Ordered list of domain names, highest priority first"
-        }
-      }
-    },
-    "token_budget": {
-      "type": "object",
-      "properties": {
-        "max_context_tokens": { "type": "integer" },
-        "domain_summary_mode": {
-          "type": "string",
-          "enum": ["full", "compact", "axioms_only", "scenario_only"]
-        },
-        "compression_strategy": { "type": "string" }
-      }
-    },
-    "evaluation": {
-      "type": "object",
-      "properties": {
-        "eval_set": { "type": "string" },
-        "minimum_pass_rate": { "type": "number", "minimum": 0, "maximum": 1 },
-        "required_dimensions": {
-          "type": "array",
-          "items": { "type": "string" }
-        }
-      }
-    }
-  }
-}