dna-sdk 0.1.0

package/dist/kernel/reports.js

@@ -0,0 +1,215 @@
+/**
+ * ReportBuilder — structured markdown reports for eval, findings, evidence, compliance.
+ *
+ * Accessed via `mi.reports.evalSummary()`, `mi.reports.findingsSummary()`,
+ * `mi.reports.evidenceManifest()`, `mi.reports.complianceMatrix(framework)`.
+ *
+ * Each report returns Markdown with YAML frontmatter.
+ *
+ * 1:1 parity with Python dna.kernel.reports.
+ */
+// ─── Severity ordering (lower = more severe) ─────────────────────────
+const SEVERITY_ORDER = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+};
+// ─── Compliance mappings ─────────────────────────────────────────────
+const COMPLIANCE_MAPPINGS = {
+    lgpd: {
+        critical: ["Art. 6 (tratamento de dados)", "Art. 46 (seguranca)"],
+        high: ["Art. 50 (boas praticas)"],
+    },
+    gdpr: {
+        critical: ["Art. 25 (data protection by design)", "Art. 35 (DPIA)"],
+        high: ["Art. 32 (security of processing)"],
+    },
+    nist_ai_rmf: {
+        critical: ["MAP-1.1 (intended purpose)", "MEASURE-2.6 (bias)"],
+        high: ["MANAGE-2.2 (risk response)"],
+    },
+};
+function frontmatter(reportType, scope) {
+    const now = new Date().toISOString();
+    return `---\nreport: ${reportType}\ngenerated_at: ${now}\nscope: ${scope}\n---\n\n`;
+}
+export class ReportBuilder {
+    _mi;
+    constructor(mi) {
+        this._mi = mi;
+    }
+    // ─── evalSummary ──────────────────────────────────────────────────
+    /** Generate an eval summary report grouped by suite.
+     *  If `suite` is given, only that suite is included. */
+    evalSummary(suite) {
+        let runs = this._mi._all("EvalRun");
+        if (suite) {
+            runs = runs.filter((r) => r.spec.suite === suite);
+        }
+        let md = frontmatter("eval_summary", this._mi.scope);
+        md += "# Eval Summary\n\n";
+        if (runs.length === 0) {
+            md += "_No eval runs found._\n";
+            return md;
+        }
+        // Group by suite, keep latest per suite (by saved_at)
+        const bySuite = new Map();
+        for (const run of runs) {
+            const spec = run.spec;
+            const s = spec.suite ?? "unknown";
+            const existing = bySuite.get(s);
+            if (!existing) {
+                bySuite.set(s, run);
+            }
+            else {
+                const newTs = spec.saved_at ?? "";
+                const oldTs = existing.spec.saved_at ?? "";
+                if (newTs > oldTs) {
+                    bySuite.set(s, run);
+                }
+            }
+        }
+        const sortedSuites = [...bySuite.entries()].sort(([a], [b]) => a.localeCompare(b));
+        for (const [suiteName, run] of sortedSuites) {
+            const spec = run.spec;
+            const total = spec.total ?? 0;
+            const passed = spec.passed ?? 0;
+            const rate = total ? `${((passed / total) * 100).toFixed(1)}%` : "N/A";
+            const agg = spec.aggregate_score;
+            const aggStr = agg != null ? agg.toFixed(2) : "N/A";
+            const cost = spec.total_cost_usd;
+            const costStr = cost != null ? `$${cost.toFixed(4)}` : "N/A";
+            const tokens = spec.total_tokens;
+            const tokensStr = tokens != null ? String(tokens) : "N/A";
+            md += `## Suite: ${suiteName}\n\n`;
+            md += `- **Pass rate:** ${rate}\n`;
+            md += `- **Aggregate score:** ${aggStr}\n`;
+            md += `- **Cost:** ${costStr}\n`;
+            md += `- **Tokens:** ${tokensStr}\n\n`;
+            const results = (spec.results ?? []);
+            if (results.length > 0) {
+                md += "| Case | Status | Score |\n";
+                md += "|------|--------|-------|\n";
+                for (const r of results) {
+                    const caseName = r.case ?? "";
+                    const status = r.status ?? "";
+                    const score = r.score;
+                    const scoreStr = score != null ? score.toFixed(2) : "-";
+                    md += `| ${caseName} | ${status} | ${scoreStr} |\n`;
+                }
+                md += "\n";
+            }
+        }
+        return md;
+    }
+    // ─── findingsSummary ──────────────────────────────────────────────
+    /** Generate a findings summary grouped by severity.
+     *  Filters out findings with severity below `minSeverity`. */
+    findingsSummary(minSeverity = "low") {
+        const findings = this._mi._all("Finding");
+        const minLevel = SEVERITY_ORDER[minSeverity] ?? 3;
+        const filtered = findings.filter((f) => {
+            const sev = f.spec.severity;
+            return (SEVERITY_ORDER[sev ?? "low"] ?? 3) <= minLevel;
+        });
+        let md = frontmatter("findings_summary", this._mi.scope);
+        md += "# Findings Summary\n\n";
+        if (filtered.length === 0) {
+            md += "_No findings found._\n";
+            return md;
+        }
+        // Group by severity
+        const bySeverity = new Map();
+        for (const f of filtered) {
+            const sev = f.spec.severity ?? "low";
+            const arr = bySeverity.get(sev) ?? [];
+            arr.push(f);
+            bySeverity.set(sev, arr);
+        }
+        for (const sev of ["critical", "high", "medium", "low"]) {
+            const group = bySeverity.get(sev);
+            if (!group || group.length === 0)
+                continue;
+            md += `## ${sev.toUpperCase()} (${group.length})\n\n`;
+            for (const f of group) {
+                const spec = f.spec;
+                const title = spec.title ?? f.name;
+                const status = spec.status ?? "open";
+                const recommendation = spec.recommendation ?? "";
+                md += `### ${title}\n\n`;
+                md += `- **Status:** ${status}\n`;
+                if (recommendation) {
+                    md += `- **Recommendation:** ${recommendation}\n`;
+                }
+                md += "\n";
+            }
+        }
+        return md;
+    }
+    // ─── evidenceManifest ─────────────────────────────────────────────
+    /** Generate a manifest of all evidence documents. */
+    evidenceManifest() {
+        const evidence = this._mi._all("Evidence");
+        let md = frontmatter("evidence_manifest", this._mi.scope);
+        md += "# Evidence Manifest\n\n";
+        if (evidence.length === 0) {
+            md += "_No evidence documents found._\n";
+            return md;
+        }
+        md += "| Event Type | Document Ref | SHA-256 | Captured At |\n";
+        md += "|------------|-------------|---------|-------------|\n";
+        for (const e of evidence) {
+            const spec = e.spec;
+            const eventType = spec.event_type ?? "";
+            const docRef = spec.document_ref ?? "";
+            const sha = spec.sha256 ?? "";
+            const shaShort = sha.length > 12 ? sha.slice(0, 12) + "..." : sha;
+            const captured = spec.captured_at ?? "";
+            md += `| ${eventType} | ${docRef} | ${shaShort} | ${captured} |\n`;
+        }
+        md += "\n";
+        return md;
+    }
+    // ─── complianceMatrix ─────────────────────────────────────────────
+    /** Generate a compliance matrix mapping findings to regulatory articles.
+     *  Supported frameworks: lgpd, gdpr, nist_ai_rmf. */
+    complianceMatrix(framework) {
+        let md = frontmatter("compliance_matrix", this._mi.scope);
+        md += `# Compliance Matrix: ${framework.toUpperCase()}\n\n`;
+        const mapping = COMPLIANCE_MAPPINGS[framework];
+        if (!mapping) {
+            const supported = Object.keys(COMPLIANCE_MAPPINGS).sort().join(", ");
+            md += `_Unknown framework: ${framework}. Supported: ${supported}._\n`;
+            return md;
+        }
+        const findings = this._mi._all("Finding");
+        md += "| Severity | Count | Regulatory Articles |\n";
+        md += "|----------|-------|--------------------|\n";
+        for (const sev of ["critical", "high", "medium", "low"]) {
+            const articles = mapping[sev] ?? [];
+            const count = findings.filter((f) => f.spec.severity === sev).length;
+            const articlesStr = articles.length > 0 ? articles.join(", ") : "-";
+            md += `| ${sev.toUpperCase()} | ${count} | ${articlesStr} |\n`;
+        }
+        md += "\n";
+        if (findings.length > 0) {
+            md += "## Findings by Article\n\n";
+            for (const sev of ["critical", "high"]) {
+                const articles = mapping[sev] ?? [];
+                const sevFindings = findings.filter((f) => f.spec.severity === sev);
+                if (sevFindings.length > 0 && articles.length > 0) {
+                    for (const article of articles) {
+                        md += `### ${article}\n\n`;
+                        for (const f of sevFindings) {
+                            const title = f.spec.title ?? f.name;
+                            md += `- ${title}\n`;
+                        }
+                        md += "\n";
+                    }
+                }
+            }
+        }
+        return md;
+    }
+}

package/dist/kernel/resolver.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Composition Engine V2 — resolution types + merge utilities (TS twin).
+ *
+ * 1:1 parity with python/dna/kernel/resolver.py
+ * (Phase 17, Story s-comp-f2-resolver / s-composition-v2-ts-twin).
+ *
+ * NB: This is the V2 *resolver* — distinct from `composition.ts` (which defines
+ * CompositionProfile dependency wiring between Kinds). The two coexist with
+ * clear naming until a future Phase 17 cleanup unifies them.
+ *
+ * This module defines the data shapes returned by `kernel.resolveDocument` plus
+ * the pure merge utilities. The actual resolver *method* lives on the Kernel
+ * class on the Python side (`Kernel.resolve_document`); porting that full
+ * orchestration (parent-chain walk + observers + granular cache) is a separate,
+ * larger concern. What the story names — "the resolver" (provenance + field
+ * merge) — is this module.
+ *
+ * Wire parity: `serialize()` emits the SAME snake_case keys as Python
+ * (scope/tenant/found/contributed/version_sha/effective_layer/
+ * contributions_by_field/is_inherited) so an HTTP consumer cannot tell which
+ * runtime produced the response.
+ *
+ * Resolution chain for (scope=S, tenant=T, kind=K, name=N):
+ *   walk Genome.parent_scope transitively, building ordered layers:
+ *     L0 = (S, T)    local + tenant overlay
+ *     L1 = (S, null) local base
+ *     L2 = (P, T)    parent + tenant overlay (if rule allows)
+ *     L3 = (P, null) parent base
+ *     ...
+ *   Apply merge strategy from LayerPolicy.composition_rules[K]:
+ *     - override_full → first non-null layer wins entirely
+ *     - field_level   → deep-merge specs; later layers contribute individual
+ *                       fields and provenance tracks which layer set each field.
+ *
+ * Bootstrap Kinds (Genome, LayerPolicy, KindDefinition) are NEVER inherited.
+ */
+/** Kinds excluded from inheritance regardless of LayerPolicy. Structural
+ *  (Genome = scope identity; LayerPolicy = the policy Kind itself;
+ *  KindDefinition = registered before docs parse, can't be overlaid). */
+export declare const BOOTSTRAP_KINDS: ReadonlySet<string>;
+/** Scope inheritance default = DENYLIST (s-platform-inherit-by-default).
+ *  When a scope has NO LayerPolicy with composition_rules, EVERY Kind defaults
+ *  to scope_inheritance=enabled EXCEPT the per-scope ledger + structural Kinds
+ *  below. Mirrors the kernel's `_NON_INHERITABLE_KINDS`. */
+export declare const DEFAULT_NON_INHERITABLE_KINDS_V1: ReadonlySet<string>;
+/** Display set ONLY (NOT the inheritance source of truth anymore): the
+ *  composition-summary endpoint iterates this to surface per-Kind
+ *  local/inherited counts in the Studio sidebar. Membership semantics live in
+ *  the denylist above. */
+export declare const DEFAULT_INHERITABLE_KINDS_V1: ReadonlySet<string>;
+/** Hard limit on parent_scope chain depth — guards against runaway loops
+ *  (cycle detection runs first, but this is a belt-and-suspenders cap). */
+export declare const MAX_RESOLUTION_DEPTH = 16;
+/** A raw manifest document dict (pre-`Document` parse) — the payload half
+ *  of a {@link Contribution}. Twin of the Py `Raw = dict[str, Any]` alias. */
+export type Raw = Record<string, unknown>;
+/** One step in the resolution chain — a single (scope, tenant) pair consulted
+ *  by the resolver.
+ *
+ *  - `found` records whether the source had ANY doc at this layer.
+ *  - `contributed` flips true when this layer ACTUALLY influenced the final
+ *    merged doc (override_full: only the winning layer; field_level: possibly
+ *    several). */
+export declare class ResolutionLayer {
+    readonly scope: string;
+    readonly tenant: string | null;
+    readonly found: boolean;
+    readonly contributed: boolean;
+    /** Version sha or content hash if the source exposes it (best-effort). */
+    readonly versionSha: string | null;
+    constructor(opts: {
+        scope: string;
+        tenant?: string | null;
+        found: boolean;
+        contributed?: boolean;
+        versionSha?: string | null;
+    });
+}
+/** Ordered list of layers consulted, highest-priority-first.
+ *
+ *  Layer order is:
+ *    [local+tenant, local+base, parent+tenant, parent+base,
+ *     grandparent+tenant, grandparent+base, ...]
+ *  The HIGHEST priority layer is first — local-tenant beats everything else. */
+export declare class ResolutionPath {
+    steps: ResolutionLayer[];
+    constructor(steps?: ResolutionLayer[]);
+    /** The single layer that became the doc's primary origin. For override_full
+     *  this is the layer whose doc was returned wholesale; for field_level it is
+     *  the highest-priority layer that contributed metadata/envelope (semantic
+     *  primary owner). */
+    get effectiveLayer(): ResolutionLayer | null;
+    /** JSON-friendly serialization for HTTP responses (snake_case = Python). */
+    serialize(): Record<string, unknown>;
+}
+/** Result of `kernel.resolveDocument` — the doc plus full provenance.
+ *
+ *  Studio renders banner/badge directly from `provenance` + `isInherited` —
+ *  no client-side detection logic needed. */
+export declare class ResolvedDocument {
+    /** The merged document (or null if not found in any layer). */
+    doc: Raw | null;
+    /** Full ordered resolution path. Includes layers consulted but not
+     *  contributing. */
+    provenance: ResolutionPath;
+    /** True when `effectiveLayer.scope != requestedScope`. Convenience derived
+     *  from provenance; Studio uses this for badge/banner toggle. */
+    isInherited: boolean;
+    /** Field-path → scope name. Populated when merge_strategy=field_level. Lets
+     *  the Detail page show `spec.persona ← _lib` annotations. */
+    contributionsByField: Record<string, string>;
+    constructor(opts: {
+        doc: Raw | null;
+        provenance: ResolutionPath;
+        isInherited: boolean;
+        contributionsByField?: Record<string, string>;
+    });
+    serialize(): Record<string, unknown>;
+}
+/** A (layer, raw-doc-or-null) pair — one contribution, highest-priority-first. */
+export type Contribution = [ResolutionLayer, Raw | null];
+/** First non-null contribution wins entirely.
+ *
+ *  Used for assetic Kinds (LottieAsset, ImagePrompt) where partial override
+ *  makes no sense (binary payload is atomic).
+ *
+ *  Input: contributions highest-priority-first.
+ *  Output: [winningRawDoc, winningLayer] or [null, null] if all miss. */
+export declare function mergeOverrideFull(contributions: Contribution[]): [Raw | null, ResolutionLayer | null];
+/** Deep-merge `spec` dicts. Higher-priority layers shadow lower per-field.
+ *  Returns [mergedDoc, primaryOriginLayer, fieldsByOrigin].
+ *
+ *  Algorithm:
+ *    - First pass: find the PRIMARY layer (highest-priority hit). Its metadata
+ *      + envelope (apiVersion, kind) carry over wholesale.
+ *    - Second pass: iterate contributions LOWEST → HIGHEST priority, overwriting
+ *      spec keys in a fresh merged dict. After the loop the highest-priority
+ *      layer's values win per-field.
+ *    - Track which layer each FINAL spec field came from so the UI can render
+ *      `spec.persona ← _lib` annotations.
+ *
+ *  Edge cases:
+ *    - All-null contributions → [null, null, {}].
+ *    - Single hit → equivalent to override_full.
+ *    - Spec missing or non-object → that layer skipped silently. */
+export declare function mergeFieldLevel(contributions: Contribution[]): [Raw | null, ResolutionLayer | null, Record<string, string>];

package/dist/kernel/resolver.js

@@ -0,0 +1,232 @@
+/**
+ * Composition Engine V2 — resolution types + merge utilities (TS twin).
+ *
+ * 1:1 parity with python/dna/kernel/resolver.py
+ * (Phase 17, Story s-comp-f2-resolver / s-composition-v2-ts-twin).
+ *
+ * NB: This is the V2 *resolver* — distinct from `composition.ts` (which defines
+ * CompositionProfile dependency wiring between Kinds). The two coexist with
+ * clear naming until a future Phase 17 cleanup unifies them.
+ *
+ * This module defines the data shapes returned by `kernel.resolveDocument` plus
+ * the pure merge utilities. The actual resolver *method* lives on the Kernel
+ * class on the Python side (`Kernel.resolve_document`); porting that full
+ * orchestration (parent-chain walk + observers + granular cache) is a separate,
+ * larger concern. What the story names — "the resolver" (provenance + field
+ * merge) — is this module.
+ *
+ * Wire parity: `serialize()` emits the SAME snake_case keys as Python
+ * (scope/tenant/found/contributed/version_sha/effective_layer/
+ * contributions_by_field/is_inherited) so an HTTP consumer cannot tell which
+ * runtime produced the response.
+ *
+ * Resolution chain for (scope=S, tenant=T, kind=K, name=N):
+ *   walk Genome.parent_scope transitively, building ordered layers:
+ *     L0 = (S, T)    local + tenant overlay
+ *     L1 = (S, null) local base
+ *     L2 = (P, T)    parent + tenant overlay (if rule allows)
+ *     L3 = (P, null) parent base
+ *     ...
+ *   Apply merge strategy from LayerPolicy.composition_rules[K]:
+ *     - override_full → first non-null layer wins entirely
+ *     - field_level   → deep-merge specs; later layers contribute individual
+ *                       fields and provenance tracks which layer set each field.
+ *
+ * Bootstrap Kinds (Genome, LayerPolicy, KindDefinition) are NEVER inherited.
+ */
+// ──────────────────────────────────────────────────────────────────────
+// Module-level constants — sensible defaults (V1 → V2 transition)
+// ──────────────────────────────────────────────────────────────────────
+/** Kinds excluded from inheritance regardless of LayerPolicy. Structural
+ *  (Genome = scope identity; LayerPolicy = the policy Kind itself;
+ *  KindDefinition = registered before docs parse, can't be overlaid). */
+export const BOOTSTRAP_KINDS = new Set([
+    "Genome",
+    "LayerPolicy",
+    "KindDefinition",
+]);
+/** Scope inheritance default = DENYLIST (s-platform-inherit-by-default).
+ *  When a scope has NO LayerPolicy with composition_rules, EVERY Kind defaults
+ *  to scope_inheritance=enabled EXCEPT the per-scope ledger + structural Kinds
+ *  below. Mirrors the kernel's `_NON_INHERITABLE_KINDS`. */
+export const DEFAULT_NON_INHERITABLE_KINDS_V1 = new Set([
+    "Story", "Issue", "Feature", "Milestone", "Roadmap",
+    "Narrative", "VibeSession", "LessonLearned", "Plan",
+    "Genome", "KindDefinition", "LayerPolicy",
+]);
+/** Display set ONLY (NOT the inheritance source of truth anymore): the
+ *  composition-summary endpoint iterates this to surface per-Kind
+ *  local/inherited counts in the Studio sidebar. Membership semantics live in
+ *  the denylist above. */
+export const DEFAULT_INHERITABLE_KINDS_V1 = new Set([
+    "Agent",
+    "LottieAsset",
+    "HtmlTemplate",
+    "Skill",
+    "ImagePrompt",
+    "Theme",
+    "PromptTemplate",
+    // s-automation-trio-extinction: JobType/HookType/ScheduleType foram extintos
+    // e unificados no Kind Automation (o inheritable herdável).
+    "Automation",
+]);
+/** Hard limit on parent_scope chain depth — guards against runaway loops
+ *  (cycle detection runs first, but this is a belt-and-suspenders cap). */
+export const MAX_RESOLUTION_DEPTH = 16;
+/** One step in the resolution chain — a single (scope, tenant) pair consulted
+ *  by the resolver.
+ *
+ *  - `found` records whether the source had ANY doc at this layer.
+ *  - `contributed` flips true when this layer ACTUALLY influenced the final
+ *    merged doc (override_full: only the winning layer; field_level: possibly
+ *    several). */
+export class ResolutionLayer {
+    scope;
+    tenant;
+    found;
+    contributed;
+    /** Version sha or content hash if the source exposes it (best-effort). */
+    versionSha;
+    constructor(opts) {
+        this.scope = opts.scope;
+        this.tenant = opts.tenant ?? null;
+        this.found = opts.found;
+        this.contributed = opts.contributed ?? false;
+        this.versionSha = opts.versionSha ?? null;
+    }
+}
+/** Ordered list of layers consulted, highest-priority-first.
+ *
+ *  Layer order is:
+ *    [local+tenant, local+base, parent+tenant, parent+base,
+ *     grandparent+tenant, grandparent+base, ...]
+ *  The HIGHEST priority layer is first — local-tenant beats everything else. */
+export class ResolutionPath {
+    steps;
+    constructor(steps = []) {
+        this.steps = steps;
+    }
+    /** The single layer that became the doc's primary origin. For override_full
+     *  this is the layer whose doc was returned wholesale; for field_level it is
+     *  the highest-priority layer that contributed metadata/envelope (semantic
+     *  primary owner). */
+    get effectiveLayer() {
+        for (const s of this.steps) {
+            if (s.found)
+                return s;
+        }
+        return null;
+    }
+    /** JSON-friendly serialization for HTTP responses (snake_case = Python). */
+    serialize() {
+        const eff = this.effectiveLayer;
+        return {
+            steps: this.steps.map((s) => ({
+                scope: s.scope,
+                tenant: s.tenant,
+                found: s.found,
+                contributed: s.contributed,
+                version_sha: s.versionSha,
+            })),
+            effective_layer: eff ? { scope: eff.scope, tenant: eff.tenant } : null,
+        };
+    }
+}
+/** Result of `kernel.resolveDocument` — the doc plus full provenance.
+ *
+ *  Studio renders banner/badge directly from `provenance` + `isInherited` —
+ *  no client-side detection logic needed. */
+export class ResolvedDocument {
+    /** The merged document (or null if not found in any layer). */
+    doc;
+    /** Full ordered resolution path. Includes layers consulted but not
+     *  contributing. */
+    provenance;
+    /** True when `effectiveLayer.scope != requestedScope`. Convenience derived
+     *  from provenance; Studio uses this for badge/banner toggle. */
+    isInherited;
+    /** Field-path → scope name. Populated when merge_strategy=field_level. Lets
+     *  the Detail page show `spec.persona ← _lib` annotations. */
+    contributionsByField;
+    constructor(opts) {
+        this.doc = opts.doc;
+        this.provenance = opts.provenance;
+        this.isInherited = opts.isInherited;
+        this.contributionsByField = opts.contributionsByField ?? {};
+    }
+    serialize() {
+        return {
+            doc: this.doc,
+            provenance: this.provenance.serialize(),
+            is_inherited: this.isInherited,
+            contributions_by_field: this.contributionsByField,
+        };
+    }
+}
+/** First non-null contribution wins entirely.
+ *
+ *  Used for assetic Kinds (LottieAsset, ImagePrompt) where partial override
+ *  makes no sense (binary payload is atomic).
+ *
+ *  Input: contributions highest-priority-first.
+ *  Output: [winningRawDoc, winningLayer] or [null, null] if all miss. */
+export function mergeOverrideFull(contributions) {
+    for (const [layer, raw] of contributions) {
+        if (raw !== null && raw !== undefined)
+            return [raw, layer];
+    }
+    return [null, null];
+}
+/** Deep-merge `spec` dicts. Higher-priority layers shadow lower per-field.
+ *  Returns [mergedDoc, primaryOriginLayer, fieldsByOrigin].
+ *
+ *  Algorithm:
+ *    - First pass: find the PRIMARY layer (highest-priority hit). Its metadata
+ *      + envelope (apiVersion, kind) carry over wholesale.
+ *    - Second pass: iterate contributions LOWEST → HIGHEST priority, overwriting
+ *      spec keys in a fresh merged dict. After the loop the highest-priority
+ *      layer's values win per-field.
+ *    - Track which layer each FINAL spec field came from so the UI can render
+ *      `spec.persona ← _lib` annotations.
+ *
+ *  Edge cases:
+ *    - All-null contributions → [null, null, {}].
+ *    - Single hit → equivalent to override_full.
+ *    - Spec missing or non-object → that layer skipped silently. */
+export function mergeFieldLevel(contributions) {
+    // First pass — find primary (highest priority hit).
+    let primary = null;
+    let primaryRaw = null;
+    for (const [layer, raw] of contributions) {
+        if (raw !== null && raw !== undefined) {
+            primary = layer;
+            primaryRaw = raw;
+            break;
+        }
+    }
+    if (primary === null || primaryRaw === null)
+        return [null, null, {}];
+    // Second pass — merge specs LOWEST to HIGHEST so highest wins per-key.
+    const mergedSpec = {};
+    const fieldsByOrigin = {};
+    for (let i = contributions.length - 1; i >= 0; i--) {
+        const [layer, raw] = contributions[i];
+        if (raw === null || raw === undefined)
+            continue;
+        const spec = raw.spec;
+        if (spec === null || spec === undefined || typeof spec !== "object" || Array.isArray(spec)) {
+            continue;
+        }
+        for (const [k, v] of Object.entries(spec)) {
+            mergedSpec[k] = v;
+            fieldsByOrigin[`spec.${k}`] = layer.scope;
+        }
+    }
+    const final = {
+        apiVersion: primaryRaw.apiVersion ?? null,
+        kind: primaryRaw.kind ?? null,
+        metadata: primaryRaw.metadata ?? {},
+        spec: mergedSpec,
+    };
+    return [final, primary, fieldsByOrigin];
+}

package/dist/kernel/resource.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Resource — self-aware document wrapper that knows its own dependencies.
+ *
+ * Replaces Document with added kindRef linkage: a Resource can resolve
+ * its own dep_filters via `deps()` without needing the full ManifestInstance.
+ */
+export interface KindLike {
+    readonly apiVersion: string;
+    readonly kind: string;
+    readonly alias: string;
+    depFilters(): Record<string, string> | null;
+}
+export interface ResourceDep {
+    /** The spec field name (e.g. "skills", "soul"). */
+    field: string;
+    /** The target kind alias (e.g. "agentskills-skill"). */
+    targetAlias: string;
+    /** Concrete names referenced (e.g. ["greet", "search"]). */
+    names: string[];
+}
+export declare class Resource {
+    readonly apiVersion: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly raw: Record<string, unknown>;
+    readonly typed: unknown;
+    readonly origin: string;
+    readonly kindRef: KindLike | null;
+    private readonly _metadataRaw;
+    private readonly _specRaw;
+    constructor(opts: {
+        apiVersion: string;
+        kind: string;
+        name: string;
+        metadata?: Record<string, unknown>;
+        spec?: Record<string, unknown>;
+        raw?: Record<string, unknown>;
+        typed?: unknown;
+        origin?: string;
+        kindRef?: KindLike | null;
+    });
+    /** Always returns Record<string, unknown> — typed metadata when available, raw dict otherwise. */
+    get metadata(): Record<string, unknown>;
+    /** Always returns Record<string, unknown> — typed spec when available, raw dict otherwise. */
+    get spec(): Record<string, unknown>;
+    /**
+     * Resolve this resource's outgoing dependency edges using kindRef.depFilters().
+     *
+     * Returns one entry per dep_filter field that has a non-empty value in spec.
+     * Scalar spec values (e.g. `soul: "brad"`) become single-element name lists.
+     * Returns empty array when kindRef is null or depFilters() returns null.
+     */
+    deps(): ResourceDep[];
+    /** Create a Resource from a raw dict. */
+    static fromRaw(raw: Record<string, unknown>, typed?: unknown, origin?: string, kindRef?: KindLike | null): Resource;
+    toString(): string;
+}