dna-sdk 0.1.0

package/dist/extensions/eval/kinds/eval-case.kind.yaml

@@ -0,0 +1,140 @@
+# EvalCase — one declarative evaluation scenario (record plane).
+#
+# Tier B port from the internal SDK's eval extension (s-dna-eval-kit).
+# Upstream, an EvalCase declared a live-agent scenario (prompt, expected
+# tool calls, trajectory mode, HITL policy, LLM-judge engines) executed by
+# a Temporal worker. What travels is the AUTHORING VOCABULARY — a case
+# declares a target, deterministic checks and tags. What does NOT travel
+# (coupled to the upstream runtime, not the Kind): trajectory_mode,
+# hitl_policy, expected_tool_calls, engines/required_engines, judge_rubric
+# and friends — all of them presuppose a live agent loop + LLM judge that
+# a notation SDK does not ship.
+#
+# Local-first evolution: the default target is the KERNEL ITSELF —
+# `target: {type: prompt, agent: X}` makes the runner compose
+# `build_prompt(agent=X)` and apply the checks to the composed prompt.
+# Deterministic, offline, and a REAL evaluation of declarative config
+# ("does my agent compose what I expect?"). LLM/live targets are an
+# extension point the HOST registers (EvalTargetPort — same
+# declare-here/execute-in-the-host split as Automation).
+#
+# tenant_scope intentionally NOT declared — permissive (base + per-tenant
+# overlay), the Evidence/Automation precedent.
+#
+# PARITY-CRITICAL package data: byte-identical mirror under both runtimes'
+# eval/kinds/ (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: eval-case
+spec:
+  target_api_version: github.com/ruinosus/dna/eval/v1
+  target_kind: EvalCase
+  alias: eval-eval-case
+  origin: github.com/ruinosus/dna/eval
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: eval-cases
+  schema:
+    type: object
+    required:
+    - checks
+    additionalProperties: false
+    properties:
+      description:
+        type: string
+        description: What this case verifies (one line).
+      target:
+        type: object
+        additionalProperties: true
+        description: What to evaluate. Omitted → the suite's target →
+          {type = prompt}. type=prompt composes the agent's system prompt
+          via build_prompt (deterministic, offline); any other type must
+          be registered by the host as an EvalTargetPort.
+        properties:
+          type:
+            type: string
+            description: Target type. 'prompt' is built in; custom types
+              are host-registered EvalTargetPorts.
+          agent:
+            type: string
+            description: Agent name for the prompt target (omitted →
+              the scope's default agent).
+          scope:
+            type: string
+            description: Scope override for the prompt target (omitted →
+              the scope the suite runs in).
+      input:
+        type: string
+        description: Free-form input for custom targets (e.g. the user
+          message an LLM target sends). The prompt target ignores it.
+      checks:
+        type: array
+        minItems: 1
+        description: Deterministic assertions applied to the text the
+          target produced. ALL checks must pass for the case to pass.
+        items:
+          type: object
+          required:
+          - type
+          additionalProperties: false
+          properties:
+            type:
+              type: string
+              enum:
+              - contains
+              - not_contains
+              - regex
+              - not_regex
+              - equals
+              - min_length
+              - max_length
+            value:
+              type:
+              - string
+              - integer
+              description: The needle/pattern (string checks) or the
+                length bound (min_length/max_length).
+            case_sensitive:
+              type: boolean
+              description: For contains/not_contains/equals. Default true.
+      expected:
+        type: string
+        description: Human-readable note of the expected outcome (shown
+          in reports; not machine-checked).
+      tags:
+        type: array
+        items:
+          type: string
+      skip:
+        type: boolean
+        description: Declared but not executed (reported as skipped).
+      skip_reason:
+        type: string
+  describe:
+    path: description
+  description_fallback_field: description
+  summary:
+    target_type:
+      path: target.type
+      default: ''
+    checks:
+      count_of: checks
+    tags: []
+  graph_style:
+    fill: '#8B5CF6'
+    stroke: '#7C3AED'
+    text_color: '#fff'
+  ascii_icon: 🧪
+  display_label: Eval Cases
+  docs: An EvalCase is one declarative evaluation scenario. It names a
+    target (default = the kernel's own prompt composition via
+    build_prompt, deterministic and offline; custom targets such as a
+    live LLM are host-registered EvalTargetPorts) and a list of
+    deterministic checks (contains/regex/equals/length) applied to the
+    text the target produced. Grouped by an EvalSuite; executed by the
+    local runner (`dna eval run`), which persists an EvalRun.

package/dist/extensions/eval/kinds/eval-run.kind.yaml

@@ -0,0 +1,134 @@
+# EvalRun — persisted result of running an EvalSuite (record plane,
+# runtime artifact; written by the local runner / `dna eval run --save`).
+#
+# Tier B port from the internal SDK's eval extension (s-dna-eval-kit).
+# Upstream, runs were written by a Temporal eval worker and carried live
+# agent telemetry. What does NOT travel (runtime-coupled, honest cut):
+# agent (the run records its resolved target instead), total_tokens,
+# total_cost_usd, aggregate_score/score_label, per-case tool calls,
+# trajectories and metric scores. What travels: the run ledger — counts,
+# timestamps, target info and per-case check results.
+#
+# tenant_scope intentionally NOT declared — permissive (base + per-tenant
+# overlay), the Evidence/Automation precedent.
+#
+# PARITY-CRITICAL package data: byte-identical mirror under both runtimes'
+# eval/kinds/ (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: eval-run
+spec:
+  target_api_version: github.com/ruinosus/dna/eval/v1
+  target_kind: EvalRun
+  alias: eval-eval-run
+  origin: github.com/ruinosus/dna/eval
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  is_runtime_artifact: true
+  storage:
+    type: yaml
+    container: eval-runs
+  schema:
+    type: object
+    required:
+    - suite
+    - total
+    - passed
+    - failed
+    - results
+    additionalProperties: false
+    properties:
+      suite:
+        type: string
+        description: Name of the EvalSuite that was executed.
+      started_at:
+        type: string
+        format: date-time
+      finished_at:
+        type: string
+        format: date-time
+      target:
+        type: object
+        additionalProperties: true
+        description: The suite-level target the run resolved (per-case
+          overrides are recorded on each result row).
+      total:
+        type: integer
+      passed:
+        type: integer
+      failed:
+        type: integer
+      errored:
+        type: integer
+      skipped:
+        type: integer
+      results:
+        type: array
+        description: Per-case outcomes, in execution order.
+        items:
+          type: object
+          required:
+          - case
+          - status
+          additionalProperties: false
+          properties:
+            case:
+              type: string
+            status:
+              type: string
+              enum:
+              - passed
+              - failed
+              - error
+              - skipped
+            target_type:
+              type: string
+              description: Resolved target type this case ran against.
+            checks:
+              type: array
+              description: Outcome of each declared check.
+              items:
+                type: object
+                required:
+                - type
+                - passed
+                additionalProperties: false
+                properties:
+                  type:
+                    type: string
+                  value:
+                    type:
+                    - string
+                    - integer
+                  passed:
+                    type: boolean
+                  detail:
+                    type: string
+                    description: Why the check failed (or the error).
+            error:
+              type: string
+              description: Error message when status=error (unknown
+                target type, target raised, case not found).
+            output_excerpt:
+              type: string
+              description: First chars of the text the target produced
+                (evidence for humans reading the run).
+  summary:
+    suite: ''
+    passed: 0
+    failed: 0
+    total: 0
+  graph_style:
+    fill: '#3B82F6'
+    stroke: '#2563EB'
+    text_color: '#fff'
+  ascii_icon: 📊
+  display_label: Eval Runs
+  docs: An EvalRun is the persisted result of one local execution of an
+    EvalSuite — pass/fail/error/skip counts, timestamps, the resolved
+    target, and per-case results with the outcome of every declared
+    check. Written by `dna eval run --save`; compared against a pinned
+    EvalBaseline to detect regressions (`dna eval run --baseline`).

package/dist/extensions/eval/kinds/eval-suite.kind.yaml

@@ -0,0 +1,87 @@
+# EvalSuite — groups EvalCases + run configuration (record plane).
+#
+# Tier B port from the internal SDK's eval extension (s-dna-eval-kit).
+# Upstream, a suite bound the cases to a live agent + worker execution
+# config. What does NOT travel (runtime/worker-coupled, honest cut):
+# agent (required upstream — here the target carries the binding),
+# timeout_per_case, max_cost_usd, model_override, comparison_key,
+# auto_findings, judge_language/judge_profile, parent_suite and the
+# red-team (pyrit) block. What travels: the grouping (cases), a default
+# target the cases inherit, and stop_on_fail.
+#
+# tenant_scope intentionally NOT declared — permissive (base + per-tenant
+# overlay), the Evidence/Automation precedent.
+#
+# PARITY-CRITICAL package data: byte-identical mirror under both runtimes'
+# eval/kinds/ (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: eval-suite
+spec:
+  target_api_version: github.com/ruinosus/dna/eval/v1
+  target_kind: EvalSuite
+  alias: eval-eval-suite
+  origin: github.com/ruinosus/dna/eval
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: eval-suites
+  dep_filters:
+    cases: eval-eval-case
+  schema:
+    type: object
+    additionalProperties: false
+    properties:
+      description:
+        type: string
+        description: What this suite evaluates (one line).
+      cases:
+        type: array
+        items:
+          type: string
+        description: EvalCase names to run, in order. Empty/omitted =
+          every EvalCase in the scope.
+      target:
+        type: object
+        additionalProperties: true
+        description: Default target for cases that do not declare their
+          own (same shape as EvalCase.target).
+        properties:
+          type:
+            type: string
+          agent:
+            type: string
+          scope:
+            type: string
+      stop_on_fail:
+        type: boolean
+        description: Stop executing remaining cases after the first
+          failed/errored case. Default false.
+      labels:
+        type: array
+        items:
+          type: string
+  describe:
+    path: description
+  description_fallback_field: description
+  summary:
+    cases:
+      count_of: cases
+    target_type:
+      path: target.type
+      default: ''
+  graph_style:
+    fill: '#6366F1'
+    stroke: '#4F46E5'
+    text_color: '#fff'
+  ascii_icon: 📋
+  display_label: Eval Suites
+  docs: An EvalSuite groups EvalCase documents and configures how the
+    local runner executes them — the case list (empty = all cases in the
+    scope), a default target the cases inherit, and stop_on_fail. Run it
+    with `dna eval run <suite>`; each execution can be persisted as an
+    EvalRun and compared against a pinned EvalBaseline.

package/dist/extensions/eval.d.ts

@@ -0,0 +1,24 @@
+/**
+ * EvalExtension — evaluation authoring as data (TS twin).
+ *
+ * Registers 4 Kinds, all from descriptors (F3 — record Kinds are data,
+ * not classes): EvalCase (eval-eval-case), EvalSuite (eval-eval-suite),
+ * EvalRun (eval-eval-run), EvalBaseline (eval-eval-baseline). The
+ * kinds/*.kind.yaml files are PARITY-CRITICAL package data —
+ * byte-identical mirrors of the Python copies
+ * (tests/test_descriptor_hash_parity.py enforces).
+ *
+ * The local synchronous runner (run_suite / compare / EvalTargetPort) is
+ * Py-primary by design (dna/extensions/eval/runner.py): the runner is a
+ * host-side execution library — the same declare-here/execute-in-the-host
+ * split as Automation, where the DECLARATION (these Kinds) is the
+ * cross-language contract and execution lives with the host. A TS host
+ * evaluates the same documents against the same schemas; a TS runner twin
+ * lands when a TS host needs one.
+ */
+import type { Extension, ExtensionHost } from "../kernel/protocols.js";
+export declare class EvalExtension implements Extension {
+    readonly name = "eval";
+    readonly version = "1.0.0";
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/eval.js

@@ -0,0 +1,31 @@
+/**
+ * EvalExtension — evaluation authoring as data (TS twin).
+ *
+ * Registers 4 Kinds, all from descriptors (F3 — record Kinds are data,
+ * not classes): EvalCase (eval-eval-case), EvalSuite (eval-eval-suite),
+ * EvalRun (eval-eval-run), EvalBaseline (eval-eval-baseline). The
+ * kinds/*.kind.yaml files are PARITY-CRITICAL package data —
+ * byte-identical mirrors of the Python copies
+ * (tests/test_descriptor_hash_parity.py enforces).
+ *
+ * The local synchronous runner (run_suite / compare / EvalTargetPort) is
+ * Py-primary by design (dna/extensions/eval/runner.py): the runner is a
+ * host-side execution library — the same declare-here/execute-in-the-host
+ * split as Automation, where the DECLARATION (these Kinds) is the
+ * cross-language contract and execution lives with the host. A TS host
+ * evaluates the same documents against the same schemas; a TS runner twin
+ * lands when a TS host needs one.
+ */
+import { loadDescriptors } from "../kernel/descriptor-loader.js";
+export class EvalExtension {
+    name = "eval";
+    version = "1.0.0";
+    register(kernel) {
+        // F3: builtin record Kinds as descriptors — package data through the
+        // same funnel as per-scope KindDefinitions (plane lint + digest
+        // idempotency + builtin conflict marker).
+        for (const raw of loadDescriptors(import.meta.url, "eval/kinds")) {
+            kernel.kindFromDescriptor(raw);
+        }
+    }
+}

package/dist/extensions/evidence/kinds/evidence.kind.yaml

@@ -0,0 +1,92 @@
+# Evidence — immutable audit event record (record plane, runtime artifact).
+# Two real shapes share the schema (s-evidence-schema-reconciliation):
+# provenance (kernel evidence_capture) and gaia worker events.
+#
+# F3 lote-3 (spec 2026-06-10-kinds-descriptor-f3): the twin EvidenceKind
+# classes (Py+TS) were DELETED — this descriptor is the single source.
+# PARITY-CRITICAL package data: byte-identical mirror under both runtimes'
+# evidence/kinds/ (tests/test_descriptor_hash_parity.py enforces).
+# Equivalence frozen in tests/test_lote3_descriptor_equivalence.py
+# (golden: tests/goldens/lote3/Evidence.golden.json).
+#
+# tenant_scope intentionally NOT declared (class never declared `scope`;
+# undeclared kinds stay permissive — declaring would change tenancy).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: evidence
+spec:
+  target_api_version: github.com/ruinosus/dna/evidence/v1
+  target_kind: Evidence
+  alias: evidence-evidence
+  origin: github.com/ruinosus/dna/evidence
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  is_runtime_artifact: true
+  storage:
+    type: yaml
+    container: evidence
+  schema:
+    type: object
+    required:
+    - event_type
+    additionalProperties: true
+    properties:
+      event_type:
+        type: string
+        enum:
+        - document_created
+        - document_modified
+        - document_deleted
+        - eval_run_completed
+        - baseline_pinned
+        - finding_created
+        - finding_status_changed
+        - custom
+        - gaia.assessment.started
+        - gaia.assessment.completed
+        - gaia.assessment.failed
+        - gaia.pillar.completed
+        - gaia.pillar.threshold_breach
+        - gaia.report.issued
+      sha256:
+        type: string
+      captured_at:
+        type: string
+        format: date-time
+      author:
+        type: string
+      document_ref:
+        type: string
+      snapshot:
+        type: object
+        additionalProperties: true
+      suite:
+        type: string
+      notes:
+        type: string
+      created_at:
+        type: string
+        format: date-time
+      payload:
+        type: object
+        additionalProperties: true
+      source_kind:
+        type: string
+      source_name:
+        type: string
+  summary:
+    event_type: ''
+    document_ref: ''
+    captured_at: ''
+  graph_style:
+    fill: '#059669'
+    stroke: '#047857'
+    text_color: '#fff'
+  ascii_icon: 📜
+  display_label: Evidence
+  docs: An Evidence document is an immutable audit event record. Captures the event
+    type, SHA-256 hash of the referenced content, timestamp, author, and optional
+    snapshot. Used by the GAIA report pipeline to provide a verifiable audit trail.

package/dist/extensions/evidence.d.ts

@@ -0,0 +1,17 @@
+/**
+ * EvidenceExtension — audit trail Kinds for the GAIA pipeline.
+ *
+ * Registers 2 KindPorts:
+ *   - Evidence       (evidence-evidence)  — immutable audit event record
+ *   - EvidencePolicy (evidence-policy)    — controls which events are auto-captured
+ *
+ * All use YAML storage with no custom reader/writer — the generic
+ * machinery handles serialization. 1:1 parity with Python.
+ */
+import type { Extension, ExtensionHost } from "../kernel/protocols.js";
+export { shouldCapture } from "../kernel/evidence-capture.js";
+export declare class EvidenceExtension implements Extension {
+    readonly name = "evidence";
+    readonly version = "1.0.0";
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/evidence.js

@@ -0,0 +1,94 @@
+/**
+ * EvidenceExtension — audit trail Kinds for the GAIA pipeline.
+ *
+ * Registers 2 KindPorts:
+ *   - Evidence       (evidence-evidence)  — immutable audit event record
+ *   - EvidencePolicy (evidence-policy)    — controls which events are auto-captured
+ *
+ * All use YAML storage with no custom reader/writer — the generic
+ * machinery handles serialization. 1:1 parity with Python.
+ */
+import { KindBase } from "../kernel/kind_base.js";
+import { SD } from "../kernel/protocols.js";
+import { makeEvidenceCaptureHandler } from "../kernel/evidence-capture.js";
+// shouldCapture is generic policy-evaluation logic that now lives in the
+// kernel (s-invert-evidence-capture-dep) so the microkernel's evidence-capture
+// handler needs no extension import. Re-exported here as the extension's
+// public API (index.ts + callers import it from this module).
+import { loadDescriptors } from "../kernel/descriptor-loader.js";
+export { shouldCapture } from "../kernel/evidence-capture.js";
+const API_VERSION = "github.com/ruinosus/dna/evidence/v1";
+// Evidence — F3 lote-3 (spec 2026-06-10-kinds-descriptor-f3): the twin
+// EvidenceKind classes (Py+TS) were DELETED — synthesized from
+// kinds/evidence.kind.yaml (parity-critical package data, byte-identical
+// Py↔TS) via the loadDescriptors loop in register(). Equivalence with the
+// extinct class frozen in test_lote3_descriptor_equivalence.py (golden:
+// tests/goldens/lote3/Evidence.golden.json).
+// ---------------------------------------------------------------------------
+// EvidencePolicy Kind
+// ---------------------------------------------------------------------------
+class EvidencePolicyKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "EvidencePolicy";
+    alias = "evidence-policy";
+    origin = "github.com/ruinosus/dna/evidence";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.yaml("evidence-policies");
+    graphStyle = { fill: "#0891B2", stroke: "#0E7490", textColor: "#fff" };
+    asciiIcon = "📑";
+    displayLabel = "Evidence Policies";
+    docs = "An EvidencePolicy controls which event types are automatically " +
+        "captured as Evidence documents. Declares the list of event types " +
+        "to watch, whether auto-capture is enabled, and retention period.";
+    dependencies() { return null; }
+    schema() {
+        return {
+            type: "object",
+            required: ["events"],
+            additionalProperties: true,
+            properties: {
+                events: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                auto_capture: { type: "boolean", default: true },
+                retention_days: { type: "integer", default: 365 },
+            },
+        };
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        return {
+            events: spec.events ?? [],
+            auto_capture: spec.auto_capture ?? true,
+            retention_days: spec.retention_days ?? 365,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export class EvidenceExtension {
+    name = "evidence";
+    version = "1.0.0";
+    register(kernel) {
+        kernel.kind(new EvidencePolicyKind());
+        // F3 lote-3: builtin record Kinds as descriptors (Evidence) —
+        // kinds/*.kind.yaml package data through the same funnel as per-scope
+        // KindDefinitions (plane lint + digest idempotency + conflict marker).
+        for (const raw of loadDescriptors(import.meta.url, "evidence/kinds")) {
+            kernel.kindFromDescriptor(raw);
+        }
+        // Register the evidence auto-capture handler when the host also
+        // exposes the RUNTIME capabilities the handler closes over
+        // (instance + writeDocument — the full Kernel does; a bare
+        // ExtensionHost slice need not). Feature-test, then narrow to the
+        // handler's own declared host contract.
+        const cap = kernel;
+        if (typeof cap.instance === "function" && typeof cap.writeDocument === "function") {
+            kernel.on("post_save", makeEvidenceCaptureHandler(cap));
+        }
+    }
+}

package/dist/extensions/federation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * FederationExtension — Phase 14r MCP Federation (schema v2, 2026-07-07).
+ *
+ * Declares the `MCPFederation` Kind: an external MCP server whose tools
+ * DNA agents consume via `Agent.spec.mcp_servers` (primary,
+ * s-mcp-servers-on-agent) or via the DNA-as-MCP-server proxy
+ * (legacy Phase 14r direction). Transports: stdio | streamable_http.
+ * Auth carries env-var NAMES only — never secret values.
+ *
+ * Schema v2 is fully backward-compatible with v1 docs: `transport`
+ * defaults to `stdio` and every new field is optional.
+ *
+ * 1:1 parity with python/dna/extensions/federation/__init__.py.
+ * The TS SDK ships schema/Kind parity only — the agent runtime (and the
+ * MCP client) is Python-only by design (spec §3).
+ */
+import type { ExtensionHost, Extension } from "../kernel/protocols.js";
+export declare class FederationExtension implements Extension {
+    readonly name = "federation";
+    readonly version = "1.0.0";
+    register(kernel: ExtensionHost): void;
+}