dna-sdk 0.10.0 → 0.12.0

package/dist/kernel/prompt-builder.js

@@ -11,6 +11,7 @@
 import Mustache from "mustache";
 import { stripPromptBlock } from "./_text.js";
 import { AgentNotFound, UnknownLayout } from "./errors.js";
+import { documentHash } from "./lock.js";
 // ---------------------------------------------------------------------------
 // PromptBuilder
 // ---------------------------------------------------------------------------
@@ -44,11 +45,14 @@ export class PromptBuilder {
             // instruction.
             throw new AgentNotFound(agentName);
         }
-        // Build context — merge backwards-compat params into enabledSlots
+        // Build context — merge backwards-compat params into enabledSlots. An
+        // explicit empty array means "disable all", ONLY undefined means "no
+        // filter" — guarding on truthiness would treat `[]` as unset and leak
+        // every skill/guardrail into the prompt (load-bearing after i-031).
         const enabledSlots = { ...(opts?.enabledSlots ?? {}) };
-        if (opts?.enabledSkills && !enabledSlots.skills)
+        if (opts?.enabledSkills !== undefined && !enabledSlots.skills)
             enabledSlots.skills = opts.enabledSkills;
-        if (opts?.enabledGuardrails && !enabledSlots.guardrails)
+        if (opts?.enabledGuardrails !== undefined && !enabledSlots.guardrails)
             enabledSlots.guardrails = opts.enabledGuardrails;
         let ctx = await this._buildContext(agentDoc, extra, enabledSlots);
         // Hook: pre_build_prompt — middleware can modify context
@@ -79,6 +83,207 @@ export class PromptBuilder {
         return prompt.replace(/\n+$/, "");
     }
     // -------------------------------------------------------------------------
+    // Explain mode — per-section provenance (s-dna-explain-provenance)
+    // -------------------------------------------------------------------------
+    /**
+     * Compose the agent AND return per-section provenance.
+     *
+     * Returns the composed prompt (byte-identical to {@link build} — explain
+     * mode never re-renders) plus a section→provenance map: the source artifact,
+     * content hash, version, and layer/overlay origin of each declared
+     * composition input (instruction, soul, skills, guardrails). Provenance is
+     * reconstructed from the kernel's own declared blocks (layout template +
+     * depFilters + flattenInContext) + the layer provenance `resolveDocument`
+     * already returns. 1:1 with Python `PromptBuilder.explain`.
+     */
+    async explain(opts) {
+        // Prompt = the ONE canonical composition (byte-equal gate: same path).
+        const prompt = await this.build(opts);
+        const tenant = opts?.tenant ?? null;
+        let agentName = opts?.agent ?? this._defaultAgentName();
+        const agentDoc = agentName ? this._findAgent(agentName) : null;
+        if (!agentDoc)
+            throw new AgentNotFound(agentName);
+        const slots = this._mergeSlots(opts);
+        const template = await this._effectiveTemplate(agentDoc);
+        const specs = this._sectionSpecs(agentDoc, template, slots);
+        const sections = [];
+        for (const [label, kp, docName] of specs) {
+            const base = await this._resolve(kp.kind, docName, null);
+            const effective = tenant ? await this._resolve(kp.kind, docName, tenant) : base;
+            sections.push(this._sectionProvenance(label, kp, docName, effective, base, tenant));
+        }
+        return { prompt, sections };
+    }
+    _defaultAgentName() {
+        const root = this.host.root;
+        if (root) {
+            const kp = this.host._kinds.get(`${root.apiVersion}\0${root.kind}`);
+            if (kp)
+                return kp.getDefaultAgentName(root);
+        }
+        return null;
+    }
+    _mergeSlots(opts) {
+        const slots = { ...(opts?.enabledSlots ?? {}) };
+        if (opts?.enabledSkills !== undefined && !slots.skills)
+            slots.skills = opts.enabledSkills;
+        if (opts?.enabledGuardrails !== undefined && !slots.guardrails)
+            slots.guardrails = opts.enabledGuardrails;
+        return slots;
+    }
+    async _effectiveTemplate(agentDoc) {
+        const spec = agentDoc.spec;
+        const kinds = this.host._kinds;
+        const agentKp = kinds.get(`${agentDoc.apiVersion}\0${agentDoc.kind}`);
+        let tmpl = spec.promptTemplate ?? spec.prompt_template ?? null;
+        if (!tmpl) {
+            const layout = spec.layout;
+            if (layout && agentKp)
+                tmpl = agentKp.layoutTemplate(layout);
+            else if (agentKp)
+                tmpl = agentKp.promptTemplate();
+        }
+        if (!tmpl)
+            return "";
+        if (tmpl.includes("/") || tmpl.endsWith(".mustache") || tmpl.endsWith(".md")) {
+            tmpl = await this.host.ref(tmpl);
+        }
+        return tmpl ?? "";
+    }
+    _kpByAlias(alias) {
+        const kinds = this.host._kinds;
+        for (const kp of kinds.values()) {
+            if (kp?.alias === alias)
+                return kp;
+        }
+        return null;
+    }
+    /**
+     * Reconstruct the ordered composition inputs → `[label, kp, name]`. A
+     * depFilter field contributes a section iff the layout actually renders it —
+     * a flatten Kind whose flatten var appears in the template (Soul →
+     * soul_content) or a Kind whose alias appears as a Mustache section
+     * (Skill/Guardrail). Non-prompt deps (tools, actors) fall out.
+     */
+    _sectionSpecs(agentDoc, template, enabledSlots) {
+        const specs = [];
+        const kinds = this.host._kinds;
+        const agentKp = kinds.get(`${agentDoc.apiVersion}\0${agentDoc.kind}`);
+        // The agent's own instruction always leads ({{{agent.instruction}}}).
+        specs.push(["instruction", agentKp, agentDoc.name]);
+        if (!agentKp)
+            return specs;
+        const filters = agentKp.depFilters() ?? {};
+        const agentSpec = agentDoc.spec;
+        for (const [specField, alias] of Object.entries(filters)) {
+            const declared = agentSpec[specField];
+            if (declared == null || declared === "" || (Array.isArray(declared) && declared.length === 0))
+                continue;
+            let names = typeof declared === "string" ? [declared] : [...declared];
+            if (specField in enabledSlots) {
+                const allowed = new Set(enabledSlots[specField]);
+                names = names.filter((n) => allowed.has(n));
+            }
+            if (names.length === 0)
+                continue;
+            const kp = this._kpByAlias(alias);
+            if (!kp)
+                continue;
+            if (!this._contributesToPrompt(kp, alias, names, template))
+                continue;
+            const singular = specField.endsWith("s") ? specField.slice(0, -1) : specField;
+            for (const n of names) {
+                const label = typeof declared === "string" ? singular : `${singular}:${n}`;
+                specs.push([label, kp, n]);
+            }
+        }
+        return specs;
+    }
+    _contributesToPrompt(kp, alias, names, template) {
+        if (kp?.flattenInContext) {
+            // Flatten Kind (Soul): spec string keys become top-level vars
+            // (soul_content). Contributes iff one of those vars is in template.
+            for (const doc of this.host.documents) {
+                if (doc.kind !== kp.kind || !names.includes(doc.name))
+                    continue;
+                for (const [k, v] of Object.entries(doc.spec)) {
+                    if (typeof v === "string" && (template.includes(`{{{${k}}}}`) || template.includes(`{{${k}}}`)))
+                        return true;
+                }
+            }
+            return false;
+        }
+        // Section Kind (Skill/Guardrail): rendered as {{#alias}} ... {{/alias}}.
+        return template.includes(`{{#${alias}}}`);
+    }
+    async _resolve(kind, name, tenant) {
+        const kernel = this.host._kernel;
+        if (!kernel?.resolveDocument)
+            return null;
+        try {
+            return await kernel.resolveDocument(this.host.scope, kind, name, { tenant });
+        }
+        catch {
+            return null; // read path, fail-soft
+        }
+    }
+    static _docHash(raw) {
+        if (!raw || typeof raw !== "object")
+            return null;
+        try {
+            return documentHash(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    _sectionProvenance(section, kp, name, effective, base, tenant) {
+        const source = PromptBuilder._sourcePath(kp, name);
+        const effRaw = effective?.doc ?? null;
+        const baseRaw = base?.doc ?? null;
+        const hash = PromptBuilder._docHash(effRaw);
+        let version = null;
+        if (effRaw && typeof effRaw === "object") {
+            const meta = effRaw.metadata ?? {};
+            const v = meta?.version;
+            version = v != null ? String(v) : null;
+        }
+        // Layer origin from the base resolution (tenant-independent). The FS
+        // tenant→base fallback would otherwise stamp every section with the
+        // tenant even without an overlay.
+        let origin = "?";
+        let isInherited = false;
+        const originSrc = base ?? effective;
+        if (originSrc) {
+            const eff = originSrc.provenance?.effectiveLayer ?? null;
+            if (eff)
+                origin = eff.scope;
+            else if (originSrc.doc == null)
+                origin = "(not found)";
+            isInherited = Boolean(originSrc.isInherited);
+        }
+        // Overridden iff a tenant was requested AND the tenant-resolved content
+        // actually differs from the base content.
+        const overriddenByTenant = Boolean(tenant && hash !== null && hash !== PromptBuilder._docHash(baseRaw));
+        return { section, kind: kp?.kind ?? "?", name, source, hash, version, origin, isInherited, overriddenByTenant };
+    }
+    static _sourcePath(kp, name) {
+        const storage = kp?.storage;
+        if (!storage)
+            return "?";
+        const pattern = storage.pattern;
+        const container = storage.container ?? "";
+        const marker = storage.marker;
+        if (pattern === "bundle")
+            return container ? `${container}/${name}/${marker}` : `${name}/${marker}`;
+        if (pattern === "yaml")
+            return container ? `${container}/${name}.yaml` : `${name}.yaml`;
+        if (pattern === "root" || pattern === "standalone")
+            return marker ?? `${name}`;
+        return container ? `${container}/${name}` : name;
+    }
+    // -------------------------------------------------------------------------
     // Private helpers
     // -------------------------------------------------------------------------
     _findAgent(name) {

package/dist/kernel/write-pipeline.d.ts

@@ -1,4 +1,5 @@
 import type { WriteHost } from "./collaborator-ports.js";
+import { type KindPort } from "./protocols.js";
 export declare class WritePipeline {
     private readonly _k;
     constructor(kernel: WriteHost);
@@ -24,6 +25,11 @@ export declare class WritePipeline {
      * - Didactic failure (install #26 pattern): names the field, the
      *   violation, and points at `dna kind show <Kind>`.
      */
+    /** Public pre-flight twin of `_validateSpecSchema` — the SAME check the
+     *  write path enforces, exposed so read-only callers (dry-run / pre-flight)
+     *  catch a schema-violating doc BEFORE the write (i-validation-shallow).
+     *  Delegates to Kernel.validateDocument. */
+    validateSpecSchema(scope: string, kind: string, name: string, raw: Record<string, unknown>, port: KindPort | null): void;
     private _validateSpecSchema;
     /**
      * Reconcile tenant + layer args + Kernel.tenant + KindPort.scope.

package/dist/kernel/write-pipeline.js

@@ -36,6 +36,13 @@ export class WritePipeline {
      * - Didactic failure (install #26 pattern): names the field, the
      *   violation, and points at `dna kind show <Kind>`.
      */
+    /** Public pre-flight twin of `_validateSpecSchema` — the SAME check the
+     *  write path enforces, exposed so read-only callers (dry-run / pre-flight)
+     *  catch a schema-violating doc BEFORE the write (i-validation-shallow).
+     *  Delegates to Kernel.validateDocument. */
+    validateSpecSchema(scope, kind, name, raw, port) {
+        this._validateSpecSchema(scope, kind, name, raw, port);
+    }
     _validateSpecSchema(scope, kind, name, raw, port) {
         const mode = WritePipeline._validationMode();
         if (mode === "off" || port === null || typeof raw !== "object" || raw === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dna-sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "DNA — Domain Notation of Anything (TypeScript SDK)",
   "type": "module",
   "license": "MIT",