dna-sdk 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export type { PreviewBlock } from "./kernel/preview.js";
 export { Document } from "./kernel/document.js";
 export { Resource, type ResourceDep } from "./kernel/resource.js";
 export { PromptBuilder } from "./kernel/prompt-builder.js";
+export type { SectionProvenance, PromptExplanation, ExplainOpts, } from "./kernel/prompt-builder.js";
 export { CompositionEngine } from "./kernel/composition-resolver.js";
 export { BOOTSTRAP_KINDS, DEFAULT_NON_INHERITABLE_KINDS_V1, DEFAULT_INHERITABLE_KINDS_V1, MAX_RESOLUTION_DEPTH, ResolutionLayer, ResolutionPath, ResolvedDocument, mergeOverrideFull, mergeFieldLevel, type Contribution, type Raw, } from "./kernel/resolver.js";
 export { CompositionResolver } from "./kernel/composition-resolver.js";

package/dist/kernel/composition-resolver.js

@@ -450,7 +450,23 @@ export class CompositionResolver {
         // multi-package conflict surface below.
         const catalogHits = [];
         for (const [layerScope, layerTenant] of chain) {
-            const raw = await k._granularDoc([layerScope, kind, name, layerTenant ?? ""]);
+            let raw;
+            try {
+                raw = await k._granularDoc([layerScope, kind, name, layerTenant ?? ""]);
+            }
+            catch (e) {
+                // A parent/catalog scope in the chain may not exist on this source
+                // (e.g. a `_lib` library scope absent in a bare checkout). Treat it
+                // as "no contribution at this layer" — the same fail-soft the
+                // instance builder applies — instead of crashing the whole resolve.
+                // (Matches Py resolve_document's FileNotFoundError guard.)
+                if (e instanceof Error && /Scope not found/.test(e.message)) {
+                    raw = null;
+                }
+                else {
+                    throw e;
+                }
+            }
             // NOTE: the Py twin registers `_layer_observers` reverse-deps here
             // (cache invalidation infra). Intentionally not ported — the TS
             // kernel has no granular cache to invalidate.

package/dist/kernel/index.d.ts

@@ -55,6 +55,18 @@ export declare const MODEL_REGISTRY_SCOPE = "_lib";
  * 1:1 parity with Python `Kernel._VOICE_POLICY_SCOPE`.
  */
 export declare const VOICE_POLICY_SCOPE = "_lib";
+/**
+ * The scope that owns the canonical Tier (DNA Cloud pricing) registry.
+ * GLOBAL like ModelProfile — queried directly regardless of the caller's
+ * scope. 1:1 parity with Python `RegistryAccessor._TIER_REGISTRY_SCOPE`.
+ */
+export declare const TIER_REGISTRY_SCOPE = "_lib";
+/**
+ * The scope that owns the canonical TenantPlan (tenant→Tier assignment)
+ * registry. GLOBAL like Tier — queried directly regardless of the caller's
+ * scope. 1:1 parity with Python `RegistryAccessor._TENANT_PLAN_REGISTRY_SCOPE`.
+ */
+export declare const TENANT_PLAN_REGISTRY_SCOPE = "_lib";
 export declare class Kernel {
     private static readonly _BOOTSTRAP_KINDS;
     private static readonly _LEGACY_NON_INHERITABLE;
@@ -181,6 +193,12 @@ export declare class Kernel {
      *  `WritePipeline.validateKindWriter` (Fase 2,
      *  s-kernel-decomp-f2-writepipeline). */
     _validateKindWriter(spec: Record<string, unknown>): void;
+    /** Validate `raw.spec` against the Kind's declared JSON Schema — the SAME
+     *  check writeDocument enforces on the write path, exposed as a public
+     *  pre-flight so read-only callers catch a schema-violating doc BEFORE the
+     *  write (i-validation-shallow). Throws SpecValidationError on violation,
+     *  honouring DNA_WRITE_VALIDATION. Twin of Python Kernel.validate_document. */
+    validateDocument(scope: string, kind: string, name: string, raw: Record<string, unknown>, apiVersion?: string): void;
     /** All registered KindPorts. Order matches registration. Facade over
      *  `this._kindreg.allPorts()` (Fase 3). */
     kindPorts(): KindPort[];
@@ -611,6 +629,38 @@ export declare class Kernel {
      * @returns The matching Document, or null on miss or error.
      */
     modelProfile(modelIdOrAlias: string): Promise<import("./document.js").Document | null>;
+    /**
+     * Resolve a Tier (DNA Cloud pricing plan) from the `_lib` scope by
+     * `tier_id` (pass 1) or `aliases[]` (pass 2). Returns the matching
+     * Document or null on miss.
+     *
+     * Always queries `TIER_REGISTRY_SCOPE` ("_lib") directly — Tier is GLOBAL
+     * and NOT in `INHERITABLE_KINDS`; any caller scope is irrelevant. The
+     * quota enforcer reads the caps from here — never hardcode calls_per_day /
+     * rate_per_sec / max_tenants in code.
+     *
+     * 1:1 parity with Python `Kernel.tier(tier_id_or_alias)`.
+     *
+     * @param idOrAlias - The tier_id string or an alias declared on the tier.
+     * @returns The matching Document, or null on miss or error.
+     */
+    tier(idOrAlias: string): Promise<import("./document.js").Document | null>;
+    /**
+     * Resolve a TenantPlan (a tenant→Tier assignment) from the `_lib` scope by
+     * `spec.tenant`. Returns the matching Document or null when no assignment
+     * exists for `tenant`.
+     *
+     * Always queries `TENANT_PLAN_REGISTRY_SCOPE` ("_lib") directly — TenantPlan
+     * is GLOBAL and NOT in `INHERITABLE_KINDS`; any caller scope is irrelevant.
+     * The billing→enforcement bridge: dna-cloud's Stripe webhook writes the doc;
+     * the SDK only reads it here. No alias pass — the match is on `tenant`.
+     *
+     * 1:1 parity with Python `Kernel.tenant_plan(tenant)`.
+     *
+     * @param tenant - The DNA tenant to resolve the plan assignment for.
+     * @returns The matching Document, or null on miss or error.
+     */
+    tenantPlan(tenant: string): Promise<import("./document.js").Document | null>;
     /**
      * Resolve a VoicePolicy from the `_lib` scope by metadata name.
      * Returns the matching Document, the first policy as a fallback, or null

package/dist/kernel/index.js

@@ -59,6 +59,18 @@ export const MODEL_REGISTRY_SCOPE = SYSTEM_SCOPE;
  * 1:1 parity with Python `Kernel._VOICE_POLICY_SCOPE`.
  */
 export const VOICE_POLICY_SCOPE = SYSTEM_SCOPE;
+/**
+ * The scope that owns the canonical Tier (DNA Cloud pricing) registry.
+ * GLOBAL like ModelProfile — queried directly regardless of the caller's
+ * scope. 1:1 parity with Python `RegistryAccessor._TIER_REGISTRY_SCOPE`.
+ */
+export const TIER_REGISTRY_SCOPE = SYSTEM_SCOPE;
+/**
+ * The scope that owns the canonical TenantPlan (tenant→Tier assignment)
+ * registry. GLOBAL like Tier — queried directly regardless of the caller's
+ * scope. 1:1 parity with Python `RegistryAccessor._TENANT_PLAN_REGISTRY_SCOPE`.
+ */
+export const TENANT_PLAN_REGISTRY_SCOPE = SYSTEM_SCOPE;
 export class Kernel {
     // ── Kind classification — DERIVED from KindPort attributes ──────────────
     // s-kernel-kindport-classification-attrs: the kernel no longer hardcodes
@@ -242,6 +254,19 @@ export class Kernel {
     _validateKindWriter(spec) {
         this._writePipeline.validateKindWriter(spec);
     }
+    /** Validate `raw.spec` against the Kind's declared JSON Schema — the SAME
+     *  check writeDocument enforces on the write path, exposed as a public
+     *  pre-flight so read-only callers catch a schema-violating doc BEFORE the
+     *  write (i-validation-shallow). Throws SpecValidationError on violation,
+     *  honouring DNA_WRITE_VALIDATION. Twin of Python Kernel.validate_document. */
+    validateDocument(scope, kind, name, raw, apiVersion) {
+        const api = apiVersion ??
+            (typeof raw === "object" && raw !== null
+                ? raw.apiVersion
+                : undefined);
+        const port = this._kindPortFor(kind, api);
+        this._writePipeline.validateSpecSchema(scope, kind, name, raw, port);
+    }
     /** All registered KindPorts. Order matches registration. Facade over
      *  `this._kindreg.allPorts()` (Fase 3). */
     kindPorts() {
@@ -1610,6 +1635,79 @@ export class Kernel {
         }
         return null;
     }
+    /**
+     * Resolve a Tier (DNA Cloud pricing plan) from the `_lib` scope by
+     * `tier_id` (pass 1) or `aliases[]` (pass 2). Returns the matching
+     * Document or null on miss.
+     *
+     * Always queries `TIER_REGISTRY_SCOPE` ("_lib") directly — Tier is GLOBAL
+     * and NOT in `INHERITABLE_KINDS`; any caller scope is irrelevant. The
+     * quota enforcer reads the caps from here — never hardcode calls_per_day /
+     * rate_per_sec / max_tenants in code.
+     *
+     * 1:1 parity with Python `Kernel.tier(tier_id_or_alias)`.
+     *
+     * @param idOrAlias - The tier_id string or an alias declared on the tier.
+     * @returns The matching Document, or null on miss or error.
+     */
+    async tier(idOrAlias) {
+        let rows;
+        try {
+            const mi = await this.instance(TIER_REGISTRY_SCOPE);
+            rows = mi._all("Tier");
+        }
+        catch {
+            return null;
+        }
+        // Pass 1: exact tier_id match
+        for (const row of rows) {
+            const spec = (row.spec ?? {});
+            if (spec.tier_id === idOrAlias) {
+                return row;
+            }
+        }
+        // Pass 2: aliases[]
+        for (const row of rows) {
+            const spec = (row.spec ?? {});
+            const aliases = (spec.aliases ?? []);
+            if (aliases.includes(idOrAlias)) {
+                return row;
+            }
+        }
+        return null;
+    }
+    /**
+     * Resolve a TenantPlan (a tenant→Tier assignment) from the `_lib` scope by
+     * `spec.tenant`. Returns the matching Document or null when no assignment
+     * exists for `tenant`.
+     *
+     * Always queries `TENANT_PLAN_REGISTRY_SCOPE` ("_lib") directly — TenantPlan
+     * is GLOBAL and NOT in `INHERITABLE_KINDS`; any caller scope is irrelevant.
+     * The billing→enforcement bridge: dna-cloud's Stripe webhook writes the doc;
+     * the SDK only reads it here. No alias pass — the match is on `tenant`.
+     *
+     * 1:1 parity with Python `Kernel.tenant_plan(tenant)`.
+     *
+     * @param tenant - The DNA tenant to resolve the plan assignment for.
+     * @returns The matching Document, or null on miss or error.
+     */
+    async tenantPlan(tenant) {
+        let rows;
+        try {
+            const mi = await this.instance(TENANT_PLAN_REGISTRY_SCOPE);
+            rows = mi._all("TenantPlan");
+        }
+        catch {
+            return null;
+        }
+        for (const row of rows) {
+            const spec = (row.spec ?? {});
+            if (spec.tenant === tenant) {
+                return row;
+            }
+        }
+        return null;
+    }
     /**
      * Resolve a VoicePolicy from the `_lib` scope by metadata name.
      * Returns the matching Document, the first policy as a fallback, or null

package/dist/kernel/instance.d.ts

@@ -16,6 +16,7 @@ import type { CompositionResult, KindPort, SourcePort } from "./protocols.js";
 import type { CompositionProfile } from "./composition-resolver.js";
 import type { PreviewBlock } from "./preview.js";
 import { PromptBuilder } from "./prompt-builder.js";
+import type { ExplainOpts, PromptExplanation } from "./prompt-builder.js";
 import { CompositionEngine } from "./composition-resolver.js";
 import { Navigator } from "./navigator.js";
 import { LockManager } from "./lock-manager.js";
@@ -199,6 +200,13 @@ export declare class ManifestInstance {
      */
     ref(value: string): Promise<string>;
     buildPrompt(opts?: BuildPromptOpts): Promise<string>;
+    /**
+     * Compose the agent AND return per-section provenance. The `prompt` field is
+     * byte-identical to {@link buildPrompt}; `sections` attributes each composed
+     * section (instruction, soul, skills, guardrails) to its source artifact,
+     * hash, version, and layer/overlay origin. See {@link PromptBuilder.explain}.
+     */
+    explainPrompt(opts?: ExplainOpts): Promise<PromptExplanation>;
     resolve(layers?: Record<string, string>): ManifestInstance;
     generateLock(): Lockfile;
     /** Auto-register Hook documents on the kernel's HookRegistry. */

package/dist/kernel/instance.js

@@ -351,6 +351,15 @@ export class ManifestInstance {
     async buildPrompt(opts) {
         return this.prompt.build(opts);
     }
+    /**
+     * Compose the agent AND return per-section provenance. The `prompt` field is
+     * byte-identical to {@link buildPrompt}; `sections` attributes each composed
+     * section (instruction, soul, skills, guardrails) to its source artifact,
+     * hash, version, and layer/overlay origin. See {@link PromptBuilder.explain}.
+     */
+    async explainPrompt(opts) {
+        return this.prompt.explain(opts);
+    }
     // -- Layers ---------------------------------------------------------------
     resolve(layers) {
         if (!layers)

package/dist/kernel/kind_base.d.ts

@@ -54,6 +54,16 @@ export declare const SCHEMA_ANNOTATION_FORMATS: readonly string[];
  *  goes through here so options stay in one place. strict:false accepts the
  *  lenient JSON Schema shapes users author in YAML. */
 export declare function createAjv(): Ajv;
+/** Normalize a spec for hashing: drop volatile + transport fields and fold a
+ *  resolved instruction_file into its inline body (s-sync-s1). Shared by
+ *  KindBase and DeclarativeKindPort so both digest identically — never a second
+ *  copy. Twin of Python KindBase._canonical_spec. */
+export declare function canonicalSpecOf(volatileSpecFields: ReadonlySet<string>, spec: Record<string, unknown>): Record<string, unknown>;
+/** Stable SHA-256 of a doc's authored identity — the source diff/sync basis
+ *  (s-sync-s1). Invariant to key order, formatting, volatile stamps, and
+ *  instruction_file-vs-inline; sensitive to real content. Twin of Python
+ *  KindBase.canonical_digest. */
+export declare function canonicalDigestOf(kind: string, volatileSpecFields: ReadonlySet<string>, doc: Document): string;
 export declare abstract class KindBase implements Omit<KindPort, "apiVersion" | "kind" | "alias" | "storage"> {
     readonly origin?: string;
     readonly isPromptTarget: boolean;

package/dist/kernel/kind_base.js

@@ -83,6 +83,36 @@ function _stableStringify(value) {
         keys.map((k) => JSON.stringify(k) + ":" + _stableStringify(obj[k])).join(",") +
         "}");
 }
+/** Normalize a spec for hashing: drop volatile + transport fields and fold a
+ *  resolved instruction_file into its inline body (s-sync-s1). Shared by
+ *  KindBase and DeclarativeKindPort so both digest identically — never a second
+ *  copy. Twin of Python KindBase._canonical_spec. */
+export function canonicalSpecOf(volatileSpecFields, spec) {
+    const out = {};
+    for (const [k, v] of Object.entries(spec ?? {})) {
+        if (volatileSpecFields.has(k))
+            continue;
+        out[k] = v;
+    }
+    delete out["source_files"]; // pure transport, never identity
+    if (out["instruction_file"] && out["instruction"]) {
+        delete out["instruction_file"]; // file-backed == inline once resolved
+    }
+    return out;
+}
+/** Stable SHA-256 of a doc's authored identity — the source diff/sync basis
+ *  (s-sync-s1). Invariant to key order, formatting, volatile stamps, and
+ *  instruction_file-vs-inline; sensitive to real content. Twin of Python
+ *  KindBase.canonical_digest. */
+export function canonicalDigestOf(kind, volatileSpecFields, doc) {
+    const spec = (doc.spec ?? {});
+    const payload = {
+        kind: doc.kind ?? kind,
+        name: doc.name ?? null,
+        spec: canonicalSpecOf(volatileSpecFields, { ...spec }),
+    };
+    return createHash("sha256").update(_stableStringify(payload), "utf8").digest("hex");
+}
 export class KindBase {
     // ---- Identity (subclasses MUST set these) -----------------------
     // abstract apiVersion: string;
@@ -233,29 +263,17 @@ export class KindBase {
         return [];
     }
     // ---- Source-sync digest (s-sync-s1; twin of Python canonical_digest) ----
+    // The algorithm lives in the module-level `canonicalSpecOf`/`canonicalDigestOf`
+    // helpers so DeclarativeKindPort (meta.ts) shares the SAME code instead of a
+    // divergent copy — a descriptor Kind digests byte-identically to its
+    // hand-written twin (twin of Python meta.py delegating to KindBase).
     canonicalSpec(spec) {
-        const out = {};
-        for (const [k, v] of Object.entries(spec ?? {})) {
-            if (this.volatileSpecFields.has(k))
-                continue;
-            out[k] = v;
-        }
-        delete out["source_files"]; // pure transport, never identity
-        if (out["instruction_file"] && out["instruction"]) {
-            delete out["instruction_file"]; // file-backed == inline once resolved
-        }
-        return out;
+        return canonicalSpecOf(this.volatileSpecFields, spec);
     }
     /** Stable SHA-256 of the doc's authored identity — basis for source
      *  diff/sync. Invariant to key order, formatting, volatile stamps, and
      *  instruction_file-vs-inline; sensitive to real content. */
     canonicalDigest(doc) {
-        const spec = (doc.spec ?? {});
-        const payload = {
-            kind: doc.kind ?? this.kind,
-            name: doc.name ?? null,
-            spec: this.canonicalSpec({ ...spec }),
-        };
-        return createHash("sha256").update(_stableStringify(payload), "utf8").digest("hex");
+        return canonicalDigestOf(this.kind, this.volatileSpecFields, doc);
     }
 }

package/dist/kernel/meta.d.ts

@@ -125,6 +125,7 @@ export declare class DeclarativeKindPort implements KindPort, DeclarativeMarker
      * Required fields surface first, optional after.
      */
     preview(doc: Document): PreviewBlock[];
+    canonicalDigest(doc: Document): string;
     static fromTyped(typedDef: TypedKindDefinition): DeclarativeKindPort;
 }
 /**

package/dist/kernel/meta.js

@@ -38,7 +38,7 @@ function hslToHex(h, s, l) {
     const toHex = (v) => Math.round((v + m) * 255).toString(16).padStart(2, "0");
     return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
 }
-import { DEFAULT_VOLATILE_SPEC_FIELDS, createAjv } from "./kind_base.js";
+import { DEFAULT_VOLATILE_SPEC_FIELDS, canonicalDigestOf, createAjv } from "./kind_base.js";
 import { StudioUIMetadata } from "./studio_ui.js";
 import { SD, } from "./protocols.js";
 /** Convert a literal YAML storage dict into a StorageDescriptor. */
@@ -714,6 +714,16 @@ export class DeclarativeKindPort {
         }
         return blocks;
     }
+    // ---- Source-sync digest (s-sync-s1) -------------------------------------
+    // Share KindBase's canonical algorithm VERBATIM (the same `canonicalDigestOf`
+    // helper) so a descriptor (F3) Kind digests byte-identically to its
+    // hand-written twin — never a divergent second copy. `this.volatileSpecFields`
+    // (KindBase defaults ∪ descriptor extras) + `this.kind` feed it. Twin of the
+    // Python fix (meta.py delegating to KindBase); keeps the port digest-capable
+    // for a future TS source-sync path (no TS consumer exercises it today).
+    canonicalDigest(doc) {
+        return canonicalDigestOf(this.kind, this.volatileSpecFields, doc);
+    }
     static fromTyped(typedDef) {
         return new DeclarativeKindPort(typedDef);
     }

package/dist/kernel/models.d.ts

@@ -517,9 +517,9 @@ export declare const AgentSpecSchema: z.ZodObject<{
     type?: string | undefined;
     skills?: string[] | undefined;
     guardrails?: string[] | undefined;
-    instruction?: string | undefined;
     promptTemplate?: string | undefined;
     layout?: string | undefined;
+    instruction?: string | undefined;
     model?: string | undefined;
     instruction_file?: string | undefined;
     tags?: string[] | undefined;
@@ -737,9 +737,9 @@ export declare const AgentSchema: z.ZodObject<{
         type?: string | undefined;
         skills?: string[] | undefined;
         guardrails?: string[] | undefined;
-        instruction?: string | undefined;
         promptTemplate?: string | undefined;
         layout?: string | undefined;
+        instruction?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         tags?: string[] | undefined;
@@ -865,9 +865,9 @@ export declare const AgentSchema: z.ZodObject<{
         type?: string | undefined;
         skills?: string[] | undefined;
         guardrails?: string[] | undefined;
-        instruction?: string | undefined;
         promptTemplate?: string | undefined;
         layout?: string | undefined;
+        instruction?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         tags?: string[] | undefined;
@@ -1516,15 +1516,15 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
 export type TypedAgentDefinition = z.output<typeof AgentDefinitionSchema>;
 export declare const GuardrailSpecSchema: z.ZodObject<{
     rules: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    severity: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    scope: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    severity: z.ZodDefault<z.ZodOptional<z.ZodEnum<["warn", "error", "hard"]>>>;
+    scope: z.ZodDefault<z.ZodOptional<z.ZodEnum<["input", "output", "both"]>>>;
 }, "strip", z.ZodTypeAny, {
-    scope: string;
-    severity: string;
+    scope: "input" | "both" | "output";
+    severity: "error" | "warn" | "hard";
     rules: string[];
 }, {
-    scope?: string | undefined;
-    severity?: string | undefined;
+    scope?: "input" | "both" | "output" | undefined;
+    severity?: "error" | "warn" | "hard" | undefined;
     rules?: string[] | undefined;
 }>;
 export declare const GuardrailSchema: z.ZodObject<{
@@ -1554,15 +1554,15 @@ export declare const GuardrailSchema: z.ZodObject<{
     }>;
     spec: z.ZodDefault<z.ZodObject<{
         rules: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-        severity: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        scope: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        severity: z.ZodDefault<z.ZodOptional<z.ZodEnum<["warn", "error", "hard"]>>>;
+        scope: z.ZodDefault<z.ZodOptional<z.ZodEnum<["input", "output", "both"]>>>;
     }, "strip", z.ZodTypeAny, {
-        scope: string;
-        severity: string;
+        scope: "input" | "both" | "output";
+        severity: "error" | "warn" | "hard";
         rules: string[];
     }, {
-        scope?: string | undefined;
-        severity?: string | undefined;
+        scope?: "input" | "both" | "output" | undefined;
+        severity?: "error" | "warn" | "hard" | undefined;
         rules?: string[] | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
@@ -1575,8 +1575,8 @@ export declare const GuardrailSchema: z.ZodObject<{
         labels: Record<string, string>;
     };
     spec: {
-        scope: string;
-        severity: string;
+        scope: "input" | "both" | "output";
+        severity: "error" | "warn" | "hard";
         rules: string[];
     };
     apiVersion: "github.com/ruinosus/dna/v1";
@@ -1593,8 +1593,8 @@ export declare const GuardrailSchema: z.ZodObject<{
     apiVersion: "github.com/ruinosus/dna/v1";
     kind: "Guardrail";
     spec?: {
-        scope?: string | undefined;
-        severity?: string | undefined;
+        scope?: "input" | "both" | "output" | undefined;
+        severity?: "error" | "warn" | "hard" | undefined;
         rules?: string[] | undefined;
     } | undefined;
 }>;
@@ -1634,9 +1634,9 @@ export declare const KindDefinitionSpecSchema: z.ZodObject<{
     description_fallback_field: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     origin: string;
+    alias: string;
     is_root: boolean;
     flatten_in_context: boolean;
-    alias: string;
     storage: Record<string, unknown>;
     plane: "composition" | "record";
     schema: Record<string, unknown>;
@@ -1753,9 +1753,9 @@ export declare const KindDefinitionSchema: z.ZodObject<{
         description_fallback_field: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
         origin: string;
+        alias: string;
         is_root: boolean;
         flatten_in_context: boolean;
-        alias: string;
         storage: Record<string, unknown>;
         plane: "composition" | "record";
         schema: Record<string, unknown>;
@@ -1818,9 +1818,9 @@ export declare const KindDefinitionSchema: z.ZodObject<{
         tenant_scope_declared: boolean;
         summary: Record<string, unknown> | null;
         origin: string;
+        alias: string;
         is_root: boolean;
         flatten_in_context: boolean;
-        alias: string;
         storage: Record<string, unknown>;
         plane: "composition" | "record";
         schema: Record<string, unknown>;
@@ -1891,9 +1891,9 @@ export declare const KindDefinitionSchema: z.ZodObject<{
         tenant_scope_declared: boolean;
         summary: Record<string, unknown> | null;
         origin: string;
+        alias: string;
         is_root: boolean;
         flatten_in_context: boolean;
-        alias: string;
         storage: Record<string, unknown>;
         plane: "composition" | "record";
         schema: Record<string, unknown>;

package/dist/kernel/models.js

@@ -396,8 +396,14 @@ export const AgentDefinitionSchema = z.object({
 // ---------------------------------------------------------------------------
 export const GuardrailSpecSchema = z.object({
     rules: z.array(z.string()).default([]),
-    severity: z.string().optional().default("warn"),
-    scope: z.string().optional().default("both"),
+    // Constrained fields — the documented severity/scope contracts. Typed as
+    // z.enum so zodSpecToJsonSchema emits `{type:"string", enum:[...]}`
+    // (i-validation-shallow): a bare z.string() degraded to `{type:"string"}` and
+    // accepted `severity: critical`/garbage on the write path. Parity: the Python
+    // twin's GuardrailSpec uses Literal[...] → the same enum shape. warn lets the
+    // turn continue; error fails the turn; hard refuses to answer.
+    severity: z.enum(["warn", "error", "hard"]).optional().default("warn"),
+    scope: z.enum(["input", "output", "both"]).optional().default("both"),
 });
 export const GuardrailSchema = z.object({
     apiVersion: z.literal("github.com/ruinosus/dna/v1"),

package/dist/kernel/prompt-builder.d.ts

@@ -9,6 +9,41 @@
  * return identical results.
  */
 import type { ManifestInstance, BuildPromptOpts } from "./instance.js";
+/** Provenance for ONE composed prompt section (instruction / soul / skill /
+ *  guardrail). Reconstructed from the layout template + depFilters +
+ *  flattenInContext plus the layer provenance `resolveDocument` returns — NOT
+ *  by re-running composition. */
+export interface SectionProvenance {
+    /** Label, e.g. `instruction` / `soul:warm` / `skill:greeting`. */
+    section: string;
+    /** Contributing Kind (`Agent` / `Soul` / `Skill` / `Guardrail`). */
+    kind: string;
+    /** Contributing document name. */
+    name: string;
+    /** Canonical source artifact path, e.g. `skills/greeting/SKILL.md`. */
+    source: string;
+    /** SHA-256 of the resolved (effective) raw doc, or null. */
+    hash: string | null;
+    /** `metadata.version` of the resolved doc, when the author set one. */
+    version: string | null;
+    /** Effective layer scope the section resolved from. */
+    origin: string;
+    /** True when `origin` differs from the requested scope (inherited). */
+    isInherited: boolean;
+    /** True when a TENANT overlay changed this section vs the base. */
+    overriddenByTenant: boolean;
+}
+/** The composed prompt PLUS a section→provenance map. `prompt` is
+ *  byte-identical to `buildPrompt` — explain mode never re-renders. */
+export interface PromptExplanation {
+    prompt: string;
+    sections: SectionProvenance[];
+}
+/** Options for {@link PromptBuilder.explain}. */
+export interface ExplainOpts extends BuildPromptOpts {
+    /** Resolve with this tenant's overlays (marks overridden sections). */
+    tenant?: string | null;
+}
 export declare class PromptBuilder {
     private host;
     constructor(host: ManifestInstance);
@@ -17,6 +52,35 @@ export declare class PromptBuilder {
      * Equivalent to `mi.buildPrompt(opts)`.
      */
     build(opts?: BuildPromptOpts): Promise<string>;
+    /**
+     * 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`.
+     */
+    explain(opts?: ExplainOpts): Promise<PromptExplanation>;
+    private _defaultAgentName;
+    private _mergeSlots;
+    private _effectiveTemplate;
+    private _kpByAlias;
+    /**
+     * 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.
+     */
+    private _sectionSpecs;
+    private _contributesToPrompt;
+    private _resolve;
+    private static _docHash;
+    private _sectionProvenance;
+    private static _sourcePath;
     private _findAgent;
     private _buildContext;
     private _renderPrompt;