@aikdna/kdna-core 0.15.7 → 0.15.9

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## v0.15.9 (2026-06-28)
+
+Story 12 — Asset inheritance (`extends` field, RFC #148 v2.x Phase 3).
+
+- **`extends` field in `manifest.schema.json`**: assets may declare
+  `extends: "@scope/name@^1.0.0"` (string) or `extends: { name, version }`
+  (object). Distinct from `dependencies` (peer composition): `extends`
+  creates a single-inheritance hierarchy where the child specialises the parent.
+- **`planLoad` extends resolution**: when a `resolveAsset` callback is provided
+  and the manifest declares `extends`, `planLoad` resolves the base asset and
+  records `extends_chain` in the plan output. Non-blocking — missing base
+  emits a WARNING issue, not a blocking error.
+- **`loadAuthorized` passes `extends_chain`** from the plan to `loadV1Unsafe`
+  so the inheritance merge is applied at load time.
+- **`loadV1Unsafe` inheritance merge**: when `extendsChain` is non-empty, the
+  base asset's content is loaded and merged with the child's content. Merge
+  rules: child axioms override parent axioms with the same `id`; parent axioms
+  not in child are inherited; same for boundaries (by `scope` text);
+  `highest_question` falls back to parent if child omits it. Non-blocking.
+- **`result.extends_chain`** and **`result.inheritance_applied`** fields added
+  to load output when inheritance is applied.
+- Blocks Story 13 (trust levels) per Section 6 sequencing.
+
+## v0.15.8 (2026-06-28)
+
+Story 11 — RAG namespace isolation (RFC #148 v2.x Phase 3).
+
+- **`rag_namespace`** field added to each entry in `resolved_dependencies`.
+  Format: `name@version` (or bare `name` when version is absent). Provides a
+  stable scoped identifier for per-component namespace isolation.
+- **`rag_isolation_policy`** object added to load output when
+  `resolved_dependencies` is non-empty:
+  `{ default: "fenced", cross_namespace_blocked: true, namespaces: [...] }`.
+  Consumers MUST NOT mix content across namespaces without explicit permission.
+- **`--as=prompt` namespace header**: each component section in multi-asset
+  prompt output is now prefixed with `[NAMESPACE: name@version]` so RAG
+  systems can attribute and isolate content per source component (per SPEC
+  §13.8 source attribution).
+- No breaking changes to existing single-asset load output or to
+  `resolved_dependencies` shape (fields are additive only).
+
 ## v0.15.7 (2026-06-28)
 
 Story 6 — dependencies runtime. Supports semver-matching local/registry dependency resolution and topological sort-based loading order.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.15.7",
+  "version": "0.15.9",
   "description": "KDNA Core library for validating, planning, and loading local .kdna judgment assets.",
   "engines": {
     "node": ">=18.0.0"

package/schema/manifest.schema.json

@@ -201,6 +201,24 @@
         "type": "string"
       }
     },
+    "extends": {
+      "description": "Asset inheritance declaration (Story 12). This asset inherits judgment content from the named base asset. Distinct from 'dependencies' (peer composition): 'extends' creates a single-inheritance hierarchy where the child specialises the parent. The child's cards override the parent's cards with the same ID; parent cards not overridden are inherited. Format: '@scope/name@semver-range' string, or an object with 'name' and optional 'version' fields.",
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Scoped asset name with optional version, e.g. '@aikdna/sales@^1.0.0'."
+        },
+        {
+          "type": "object",
+          "required": ["name"],
+          "additionalProperties": false,
+          "properties": {
+            "name":    { "type": "string", "description": "Scoped asset name, e.g. '@aikdna/sales'." },
+            "version": { "type": "string", "description": "Semver range, e.g. '^1.0.0'. Defaults to '*' if absent." }
+          }
+        }
+      ]
+    },
     "encryption": { "type": "object" },
     "load_contract": { "$ref": "load-contract.schema.json" },
     "scope": { "type": "object" },

package/src/v1/index.js

@@ -1273,6 +1273,55 @@ function planLoad(inputPath, opts = {}) {
     }
   }
 
+  // Resolve extends chain if declared (Story 12)
+  // 'extends' is single-inheritance: child overrides parent's cards with same ID.
+  // Distinct from 'dependencies' (peer composition).
+  if (manifest.extends) {
+    const extendsDecl = manifest.extends;
+    const extendsName = typeof extendsDecl === 'string'
+      ? extendsDecl.replace(/@[^@]+$/, '') || extendsDecl  // strip @version for resolver key
+      : extendsDecl.name;
+    const extendsVersion = typeof extendsDecl === 'string'
+      ? (extendsDecl.match(/@([^@]+)$/) || [])[1] || '*'
+      : (extendsDecl.version || '*');
+
+    if (typeof opts.resolveAsset === 'function') {
+      try {
+        const baseAsset = opts.resolveAsset(extendsName);
+        if (!baseAsset) {
+          plan.issues.push(buildLoadPlanIssue(
+            'KDNA_EXTENDS_NOT_FOUND',
+            'warning',
+            `Base asset "${extendsName}" declared in 'extends' could not be resolved. Inheritance chain incomplete.`
+          ));
+        } else if (baseAsset.manifest && !satisfies(baseAsset.version, extendsVersion)) {
+          plan.issues.push(buildLoadPlanIssue(
+            'KDNA_EXTENDS_VERSION_MISMATCH',
+            'warning',
+            `Base asset "${extendsName}@${baseAsset.version}" does not satisfy extends range "${extendsVersion}".`
+          ));
+        } else if (baseAsset.path) {
+          plan.extends_chain = [
+            { name: extendsName, version: baseAsset.version || extendsVersion, path: baseAsset.path },
+          ];
+        }
+      } catch (err) {
+        plan.issues.push(buildLoadPlanIssue(
+          'KDNA_EXTENDS_RESOLUTION_FAILED',
+          'warning',
+          `extends resolution failed: ${err.message}`
+        ));
+      }
+    } else {
+      // No resolver: extends chain unresolvable — warn, don't block
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_EXTENDS_RESOLVER_MISSING',
+        'warning',
+        `Asset declares 'extends: ${JSON.stringify(manifest.extends)}' but no resolver was provided. Inheritance chain will not be applied.`
+      ));
+    }
+  }
+
   if (resolvedDeps.length > 0) {
     plan.resolved_dependencies = resolvedDeps.map(dep => ({
       name: dep.name,
@@ -1662,7 +1711,12 @@ function loadAuthorized(inputPath, opts = {}) {
     err.plan = plan;
     throw err;
   }
-  const mergedOpts = { ...opts, resolvedDependencies: plan.resolved_dependencies };
+  const mergedOpts = {
+    ...opts,
+    resolvedDependencies: plan.resolved_dependencies,
+    // Pass extends_chain from plan to loadV1Unsafe so inheritance is applied (Story 12)
+    extendsChain: plan.extends_chain || [],
+  };
   return loadV1Unsafe(inputPath, mergedOpts);
 }
 
@@ -1844,18 +1898,84 @@ function loadV1Unsafe(inputPath, opts = {}) {
     throw new Error(`unknown load profile: ${profile}`);
   }
 
-  if (opts.resolvedDependencies && opts.resolvedDependencies.length > 0) {
+  // Asset inheritance (Story 12): if the manifest declares 'extends' and
+  // the plan resolved an extends_chain, load the base asset and merge its
+  // content with the child's content. Child cards with the same ID override
+  // the parent's; parent cards not overridden are inherited.
+  if (opts.extendsChain && opts.extendsChain.length > 0 && result.content) {
+    try {
+      const base = opts.extendsChain[0];
+      const baseLoaded = loadV1Unsafe(base.path, {
+        ...opts,
+        resolvedDependencies: [],
+        extendsChain: [],
+      });
+      if (baseLoaded && baseLoaded.content) {
+        const bc = baseLoaded.content;
+        const cc = result.content;
+        // Merge axioms: child overrides by id; parent axioms not in child are added
+        if (bc.axioms || cc.axioms) {
+          const childIds = new Set((cc.axioms || []).map((a) => a.id).filter(Boolean));
+          const inheritedAxioms = (bc.axioms || []).filter((a) => a.id && !childIds.has(a.id));
+          cc.axioms = [...inheritedAxioms, ...(cc.axioms || [])];
+        }
+        // Merge boundaries: child overrides by scope text; parent not overridden are inherited
+        if (bc.boundaries || cc.boundaries) {
+          const childScopes = new Set(
+            (cc.boundaries || []).map((b) => (b.scope || '').toLowerCase().trim()),
+          );
+          const inheritedBoundaries = (bc.boundaries || []).filter(
+            (b) => !childScopes.has((b.scope || '').toLowerCase().trim()),
+          );
+          cc.boundaries = [...inheritedBoundaries, ...(cc.boundaries || [])];
+        }
+        // Inherit highest_question from parent if child doesn't declare one
+        if (!cc.highest_question && bc.highest_question) {
+          cc.highest_question = bc.highest_question;
+        }
+        result.extends_chain = opts.extendsChain.map((e) => ({
+          name: e.name,
+          version: e.version,
+          path: e.path,
+        }));
+        result.inheritance_applied = true;
+      }
+    } catch (_) {
+      // extends merge is best-effort — never block load
+      result.inheritance_applied = false;
+    }
+  }
+
+   if (opts.resolvedDependencies && opts.resolvedDependencies.length > 0) {
     result.resolved_dependencies = opts.resolvedDependencies.map(dep => {
       const depLoaded = loadV1Unsafe(dep.path, { ...opts, resolvedDependencies: [] });
+      // RAG namespace (Story 11): scoped identifier for namespace isolation.
+      // Format: name@version (or just name when version is absent).
+      const ragNamespace = dep.name
+        ? (dep.version ? `${dep.name}@${dep.version}` : dep.name)
+        : null;
       return {
         name: dep.name,
         version: dep.version,
         path: dep.path,
+        rag_namespace: ragNamespace,
         status: depLoaded.status,
         profile: depLoaded.profile,
         content: depLoaded.content
       };
     });
+
+    // RAG isolation policy (Story 11): consumers MUST NOT mix content
+    // across namespaces without explicit permission. cross_namespace_blocked
+    // is the default; a consumer may opt in to cross-namespace access by
+    // setting its own policy, but Core never does it silently.
+    result.rag_isolation_policy = {
+      default: 'fenced',
+      cross_namespace_blocked: true,
+      namespaces: result.resolved_dependencies
+        .map(d => d.rag_namespace)
+        .filter(Boolean),
+    };
   }
 
   if (as === 'prompt') {
@@ -1883,11 +2003,17 @@ function loadV1Unsafe(inputPath, opts = {}) {
     if (c.note) text += 'Note: ' + c.note + '\n';
     
     let textOut = text.trim();
-    if (opts.resolvedDependencies && opts.resolvedDependencies.length > 0) {
+   if (opts.resolvedDependencies && opts.resolvedDependencies.length > 0) {
       for (const dep of opts.resolvedDependencies) {
         const depLoaded = loadV1Unsafe(dep.path, { ...opts, resolvedDependencies: [] });
         if (depLoaded.text) {
-          textOut += '\n\n---\n\n' + depLoaded.text;
+          // Namespace header (Story 11): each component section is prefixed
+          // with [NAMESPACE: id] so consumers can isolate RAG content per source.
+          const ns = dep.name
+            ? (dep.version ? `${dep.name}@${dep.version}` : dep.name)
+            : null;
+          const nsHeader = ns ? `[NAMESPACE: ${ns}]\n` : '';
+          textOut += '\n\n---\n\n' + nsHeader + depLoaded.text;
         }
       }
     }