dna-sdk 0.1.0

package/dist/extensions/automation/write-guards.js

@@ -0,0 +1,153 @@
+/**
+ * Automation-owned write-path guards (s-tier-a-automation).
+ *
+ * One `pre_save` VETO hook that makes an Automation write *fully valid or
+ * not persisted*, covering what is Automation's OWN:
+ *
+ * - **Semantics the schema cannot express:**
+ *
+ *    - **cron expression** (`on.type: cron`) — parsed by a zero-dependency
+ *      5-field validator (documented decision: a cron lib would be a
+ *      runtime dep for one field; the grammar below covers the standard
+ *      crontab core — `*`, numbers, ranges, lists, steps — and rejects the
+ *      rest loudly. Name aliases like `JAN`/`MON` are NOT supported.)
+ *    - **hook name** (`on.type: hook`) — must belong to the kernel's typed
+ *      hook vocabulary `KNOWN_HOOK_NAMES` (s-dna-typed-hook-names). The
+ *      HookRegistry itself tolerates custom names (warn-once), but an
+ *      Automation is DATA a host executor dispatches on: a misspelled hook
+ *      would be declared, listed, and silently never fire — so here the
+ *      unknown name is a veto, not a warning.
+ *
+ * The Python twin has one extra FIRST step this side does not need: PyYAML
+ * reads a bare `on:` key as boolean `True` (YAML 1.1), so the Py guard
+ * heals a top-level `True` spec key back to `"on"` before validating.
+ * js-yaml keeps `on` a string — no trap, no step.
+ *
+ * Schema SHAPE at write time (originally this guard's step 1) is no longer
+ * Automation-specific: `s-write-path-validation` (i-008) generalized it —
+ * `WritePipeline.write` validates every doc's spec against the Kind's
+ * declared `schema()` after the veto hooks run. This guard keeps only the
+ * semantics JSON Schema cannot express.
+ *
+ * A throw from the guard vetoes the write (nothing is persisted). The hook
+ * fires for EVERY `kernel.writeDocument` regardless of `skipHooks` — it is
+ * an integrity gate, not a notification. 1:1 parity with Python
+ * `dna.extensions.automation.write_guards`.
+ */
+import { KNOWN_HOOK_NAMES } from "../../kernel/hooks.js";
+const KIND = "Automation";
+// After helix (10/20/30) and SDLC bitemporal (40).
+export const PRIORITY_TRIGGER_GUARD = 50;
+// [label, lo, hi] per cron field, in order. dow accepts 0-7 (0 and 7 both
+// mean Sunday, matching crontab).
+const CRON_FIELDS = [
+    ["minute", 0, 59],
+    ["hour", 0, 23],
+    ["day-of-month", 1, 31],
+    ["month", 1, 12],
+    ["day-of-week", 0, 7],
+];
+function cronError(expr, detail) {
+    return new Error(`invalid cron expression ${JSON.stringify(expr)}: ${detail}. Expected ` +
+        `5 whitespace-separated fields 'min hour dom mon dow' (e.g. ` +
+        `'0 10 * * 1,3,5'); each field is '*', a number, a range 'a-b', a ` +
+        `list 'a,b,c' or a step '*/n' / 'a-b/n'. Name aliases (JAN/MON) ` +
+        `are not supported.`);
+}
+const DIGITS = /^\d+$/;
+/**
+ * Validate a 5-field cron expression. Throws on the first problem
+ * (didactic message); returns void when valid.
+ */
+export function validateCronExpression(expr) {
+    const fields = expr.split(/\s+/).filter((f) => f.length > 0);
+    if (fields.length !== 5) {
+        throw cronError(expr, `expected 5 fields, got ${fields.length}`);
+    }
+    for (let i = 0; i < 5; i++) {
+        const value = fields[i];
+        const [label, lo, hi] = CRON_FIELDS[i];
+        for (const item of value.split(",")) {
+            if (!item)
+                throw cronError(expr, `empty list item in ${label} field`);
+            const slash = item.indexOf("/");
+            const base = slash === -1 ? item : item.slice(0, slash);
+            if (slash !== -1) {
+                const step = item.slice(slash + 1);
+                if (!DIGITS.test(step) || parseInt(step, 10) < 1) {
+                    throw cronError(expr, `step '/${step}' in ${label} field must be a positive integer`);
+                }
+                if (base === "") {
+                    throw cronError(expr, `step without a base in ${label} field`);
+                }
+            }
+            if (base === "*")
+                continue;
+            const dash = base.indexOf("-");
+            const bounds = dash === -1
+                ? [base]
+                : [base.slice(0, dash), base.slice(dash + 1)];
+            for (const bound of bounds) {
+                if (!DIGITS.test(bound)) {
+                    throw cronError(expr, `${JSON.stringify(bound)} in ${label} field is not a number`);
+                }
+                const n = parseInt(bound, 10);
+                if (n < lo || n > hi) {
+                    throw cronError(expr, `${n} out of range ${lo}-${hi} for ${label}`);
+                }
+            }
+            if (dash !== -1 && parseInt(bounds[0], 10) > parseInt(bounds[1], 10)) {
+                throw cronError(expr, `inverted range ${JSON.stringify(base)} in ${label} field`);
+            }
+        }
+    }
+}
+/**
+ * Veto an Automation write that is not fully valid.
+ *
+ * Checks the semantics JSON Schema cannot express (cron grammar,
+ * hook-name vocabulary). Schema SHAPE is validated by the kernel's
+ * generic write-path step (s-write-path-validation, i-008), which runs
+ * after the veto hooks — this guard no longer duplicates it.
+ */
+export function automationTriggerGuard(ctx) {
+    if (ctx.kind !== KIND || typeof ctx.raw !== "object" || ctx.raw === null) {
+        return;
+    }
+    const spec = ctx.raw.spec;
+    if (typeof spec !== "object" || spec === null)
+        return;
+    // Semantics the schema cannot express (shape itself is the kernel's
+    // generic write-path validation, which runs after the veto hooks).
+    const on = spec.on;
+    if (typeof on !== "object" || on === null)
+        return;
+    const onType = on.type;
+    if (onType === "cron") {
+        const cron = on.cron;
+        if (typeof cron === "string")
+            validateCronExpression(cron);
+    }
+    else if (onType === "hook") {
+        const hook = on.hook;
+        if (typeof hook === "string" && !KNOWN_HOOK_NAMES.includes(hook)) {
+            throw new Error(`Automation ${JSON.stringify(ctx.name)} declares on.hook=` +
+                `${JSON.stringify(hook)}, which is not a kernel lifecycle hook. ` +
+                `Known hooks: ${JSON.stringify([...KNOWN_HOOK_NAMES].sort())}. A ` +
+                `misspelled hook would be declared but never fire — fix the name ` +
+                `(the vocabulary is typed: HookName in kernel/hooks).`);
+        }
+    }
+}
+/**
+ * Wire the Automation write guard as a `pre_save` veto hook.
+ *
+ * The key makes the registration idempotent (re-loading the extension
+ * onto a shared HookRegistry replaces instead of stacking duplicates).
+ */
+export function registerWriteGuards(kernel) {
+    kernel.hooks.onVeto("pre_save", automationTriggerGuard, {
+        priority: PRIORITY_TRIGGER_GUARD,
+        key: "automation.trigger-guard",
+    });
+}

package/dist/extensions/automation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AutomationExtension — declarative background automation as data.
+ *
+ * 1:1 parity with Python `dna.extensions.automation`.
+ *
+ * Registers 1 Kind, from a descriptor (F3 — record Kinds are data, not
+ * classes):
+ *
+ *   - Automation (`dna-automation`) — one doc declares WHEN background
+ *     work fires (`on: {type: cron|hook|tool, ...}`) and WHAT runs
+ *     (`runner: {kind: agent|tool, ref}` + `agent_directive` / `input` /
+ *     result templating / spoken copy / `safety`). Tier A port from the
+ *     internal SDK's automation extension (s-tier-a-automation) —
+ *     upstream, this Kind unified an async-tool / bus-event / cron trio
+ *     and killed hardcoded dispatch: adding or retargeting an automation
+ *     is writing one YAML, zero deploy.
+ *
+ * What travels vs what does not (honest evolution):
+ *
+ *   - The DECLARATION travels: the Kind (descriptor), write-time
+ *     validation (`automation/write-guards.ts`: 5-field cron parse + hook
+ *     names against the kernel's typed `KNOWN_HOOK_NAMES` vocabulary) and
+ *     the query helpers (`automationsFor` / `triggerKey`) a host executor
+ *     reads.
+ *   - EXECUTION does not: the SDK has no scheduler, bus or worker. The
+ *     host reads Automation docs via the query helpers and runs them —
+ *     the same declare-here/execute-in-the-host pattern as the CLI's
+ *     `register_post_transition_hook`. The runner contract + a minimal
+ *     example live in docs/concepts/builtin-kinds.md.
+ *
+ * Inheritable ⇒ never TENANTED: Automation is an inheritable `_lib`
+ * default (it is in `DEFAULT_INHERITABLE_KINDS_V1`) → tenancy PERMISSIVE
+ * (no `tenant_scope` in the descriptor): base writable in `_lib` +
+ * per-tenant override via overlay.
+ */
+import type { ExtensionHost, Extension } from "../kernel/protocols.js";
+export declare class AutomationExtension implements Extension {
+    name: string;
+    version: string;
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/automation.js

@@ -0,0 +1,54 @@
+/**
+ * AutomationExtension — declarative background automation as data.
+ *
+ * 1:1 parity with Python `dna.extensions.automation`.
+ *
+ * Registers 1 Kind, from a descriptor (F3 — record Kinds are data, not
+ * classes):
+ *
+ *   - Automation (`dna-automation`) — one doc declares WHEN background
+ *     work fires (`on: {type: cron|hook|tool, ...}`) and WHAT runs
+ *     (`runner: {kind: agent|tool, ref}` + `agent_directive` / `input` /
+ *     result templating / spoken copy / `safety`). Tier A port from the
+ *     internal SDK's automation extension (s-tier-a-automation) —
+ *     upstream, this Kind unified an async-tool / bus-event / cron trio
+ *     and killed hardcoded dispatch: adding or retargeting an automation
+ *     is writing one YAML, zero deploy.
+ *
+ * What travels vs what does not (honest evolution):
+ *
+ *   - The DECLARATION travels: the Kind (descriptor), write-time
+ *     validation (`automation/write-guards.ts`: 5-field cron parse + hook
+ *     names against the kernel's typed `KNOWN_HOOK_NAMES` vocabulary) and
+ *     the query helpers (`automationsFor` / `triggerKey`) a host executor
+ *     reads.
+ *   - EXECUTION does not: the SDK has no scheduler, bus or worker. The
+ *     host reads Automation docs via the query helpers and runs them —
+ *     the same declare-here/execute-in-the-host pattern as the CLI's
+ *     `register_post_transition_hook`. The runner contract + a minimal
+ *     example live in docs/concepts/builtin-kinds.md.
+ *
+ * Inheritable ⇒ never TENANTED: Automation is an inheritable `_lib`
+ * default (it is in `DEFAULT_INHERITABLE_KINDS_V1`) → tenancy PERMISSIVE
+ * (no `tenant_scope` in the descriptor): base writable in `_lib` +
+ * per-tenant override via overlay.
+ */
+import { loadDescriptors } from "../kernel/descriptor-loader.js";
+import { registerWriteGuards } from "./automation/write-guards.js";
+export class AutomationExtension {
+    name = "automation";
+    version = "1.0.0";
+    register(kernel) {
+        // F3: Automation ships as kinds/automation.kind.yaml package data
+        // (byte-identical Py↔TS mirror), registered through the SAME funnel as
+        // per-scope KindDefinitions (plane lint + digest idempotency + builtin
+        // conflict marker).
+        for (const raw of loadDescriptors(import.meta.url, "automation/kinds")) {
+            kernel.kindFromDescriptor(raw);
+        }
+        // Write-time semantic validation the JSON Schema cannot express: cron
+        // expression parse + hook-name vocabulary (pre_save veto, helix
+        // write-guards pattern).
+        registerWriteGuards(kernel);
+    }
+}

package/dist/extensions/collab.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CollabExtension — collaboration primitives (Comment Kind).
+ *
+ * Registers 1 KindPort:
+ *   - Comment (collab-comment) — a remark or status change attached to any document
+ *
+ * Comments can be attached to any target document via `target_ref`.
+ * They enable audit trails, discussions, and status-change history.
+ * 1:1 parity with Python.
+ */
+import type { ExtensionHost, Extension } from "../kernel/protocols.js";
+export declare class CollabExtension implements Extension {
+    readonly name = "collab";
+    readonly version = "1.0.0";
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/collab.js

@@ -0,0 +1,79 @@
+/**
+ * CollabExtension — collaboration primitives (Comment Kind).
+ *
+ * Registers 1 KindPort:
+ *   - Comment (collab-comment) — a remark or status change attached to any document
+ *
+ * Comments can be attached to any target document via `target_ref`.
+ * They enable audit trails, discussions, and status-change history.
+ * 1:1 parity with Python.
+ */
+import { KindBase } from "../kernel/kind_base.js";
+import { SD } from "../kernel/protocols.js";
+const API_VERSION = "github.com/ruinosus/dna/collab/v1";
+// ---------------------------------------------------------------------------
+// CommentKind
+// ---------------------------------------------------------------------------
+class CommentKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "Comment";
+    alias = "collab-comment";
+    origin = "github.com/ruinosus/dna/collab";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.yaml("comments");
+    graphStyle = { fill: "#F59E0B", stroke: "#D97706", textColor: "#fff" };
+    asciiIcon = "💬";
+    displayLabel = "Comments";
+    docs = "";
+    // Comment can point to ANY kind via target_ref — no typed dep filter
+    // because target can be Finding, EvalCase, Agent, etc.
+    depFilters() { return {}; }
+    schema() {
+        return {
+            type: "object",
+            required: ["target_ref", "author", "body", "type", "created_at"],
+            additionalProperties: true,
+            properties: {
+                target_ref: { type: "string", description: "Kind:name of the target document" },
+                author: { type: "string" },
+                body: { type: "string" },
+                type: {
+                    type: "string",
+                    enum: ["note", "status_change", "assignment", "system"],
+                    default: "note",
+                },
+                created_at: { type: "string", format: "date-time" },
+                // Fields when type=status_change:
+                from_status: { type: "string" },
+                to_status: { type: "string" },
+                // Fields when type=assignment:
+                assignee: { type: "string" },
+                // Edits/attachments (future):
+                edited_at: { type: "string" },
+                attachments: { type: "array", items: { type: "string" } },
+            },
+        };
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        const body = spec.body ?? "";
+        return {
+            target_ref: spec.target_ref ?? "",
+            author: spec.author ?? "",
+            type: spec.type ?? "note",
+            body_preview: body ? body.slice(0, 80) : "",
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export class CollabExtension {
+    name = "collab";
+    version = "1.0.0";
+    register(kernel) {
+        kernel.kind(new CommentKind());
+    }
+}

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

@@ -0,0 +1,118 @@
+# Doc — one page of in-product documentation (record plane, authored content).
+#
+# Tier A port from the internal SDK's doc extension (s-tier-a-doc-kind). What
+# travels is the CORE: a Doc is structured content — a markdown ``body`` plus
+# sidebar metadata (icon / subtitle / summary / order / locale / enabled),
+# Diátaxis ``kind_of`` and a free-form ``category`` — exactly the corpus
+# ``dna docs list/show`` reads. The authoring shape is preserved: a bundle
+# ``docs/<name>/DOC.md`` (YAML frontmatter + markdown body), handled entirely
+# by the generic bundle machinery (``body_field: body``) — no custom
+# reader/writer, no class. ``tags`` is a DNA addition (free-form labels),
+# not an upstream field.
+#
+# Deliberately NOT ported (coupled to the upstream product's help-center
+# service, not to the Kind):
+#   - ``data_sections`` + ``live_diagrams`` (the ``<!-- DATA: … -->`` /
+#     ``<!-- LIVE: … -->`` body placeholders) — resolved by upstream service
+#     endpoints (live kernel-introspection tables + server-rendered
+#     diagrams) that have no DNA equivalent;
+#   - ``spec.assets`` (sibling sub-markdown/drawio files lifted into the
+#     spec) — a UI rendering concern; sibling files still live in the
+#     bundle directory, they are just not aggregated into the document;
+#   - the ``featured`` landing-page curation flag, the "blank Doc" template
+#     scaffold, and the widget-hint ``ui_schema`` bag — upstream product
+#     UX; hosts can derive forms from the JSON Schema below.
+#
+# PARITY-CRITICAL package data: byte-identical mirror under both runtimes'
+# doc/kinds/ (tests/test_descriptor_hash_parity.py enforces).
+#
+# tenant_scope intentionally NOT declared — permissive (base doc + optional
+# per-tenant overlay). Docs are shared per-scope content a tenant may
+# legitimately override; the máxima "inheritable ⇒ never tenanted" holds.
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: doc
+spec:
+  target_api_version: github.com/ruinosus/dna/doc/v1
+  target_kind: Doc
+  alias: dna-doc
+  origin: github.com/ruinosus/dna/doc
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: bundle
+    container: docs
+    marker: DOC.md
+    body_field: body
+  spec_defaults:
+    order: 999
+    locale: pt-BR
+    enabled: true
+  schema:
+    type: object
+    required:
+    - body
+    additionalProperties: false
+    properties:
+      body:
+        type: string
+        description: Markdown body of the page — the DOC.md content below the
+          frontmatter.
+      icon:
+        type: string
+        description: Emoji or short string shown next to the title.
+      subtitle:
+        type: string
+        description: One-line subtitle shown under the title.
+      summary:
+        type: string
+        description: 1-2 sentences for the topic header card / previews.
+      order:
+        type: integer
+        description: Sort order in the sidebar (ascending).
+      locale:
+        type: string
+        description: Content locale (e.g. pt-BR, en). ``dna docs`` filters
+          on it.
+      enabled:
+        type: boolean
+        description: If false, the page is hidden from listings.
+      kind_of:
+        enum:
+        - tutorial
+        - how_to
+        - reference
+        - explanation
+        - null
+        description: Diátaxis classification (learning- / task- /
+          information- / understanding-oriented). Null = uncategorized.
+      category:
+        type:
+        - string
+        - 'null'
+        description: Free-form sidebar grouping (e.g. "Getting started").
+          Null falls back to a flat list.
+      tags:
+        type: array
+        items:
+          type: string
+        description: Free-form labels for filtering and search.
+  describe:
+    path: subtitle
+  description_fallback_field: subtitle
+  graph_style:
+    fill: '#0EA5E9'
+    stroke: '#0284C7'
+    text_color: '#fff'
+  ascii_icon: 📘
+  display_label: Docs
+  docs: A Doc is one page of in-product documentation. The marker is
+    ``docs/<name>/DOC.md`` — YAML frontmatter (icon, subtitle, summary,
+    order, locale, enabled, kind_of, category, tags) plus a markdown body
+    that lands in ``spec.body``. The page title is ``metadata.description``.
+    ``kind_of`` follows Diátaxis (tutorial/how_to/reference/explanation);
+    ``category`` groups the sidebar; ``locale`` lets one corpus serve
+    multiple languages. This is the Kind behind ``dna docs list/show``.

package/dist/extensions/doc.d.ts

@@ -0,0 +1,25 @@
+/**
+ * DocExtension — the in-product documentation Kind.
+ *
+ * Registers 1 Kind:
+ *   - Doc (dna-doc) — one page of in-product documentation: a markdown
+ *     `body` + sidebar metadata (icon/subtitle/summary/order/locale/
+ *     enabled/kind_of/category/tags). The corpus `dna docs list/show`
+ *     reads is made of these.
+ *
+ * Pure descriptor extension (F3): the Kind is data — `doc/kinds/
+ * doc.kind.yaml` — synthesized via `kernel.kindFromDescriptor`; the
+ * bundle storage (`docs/<name>/DOC.md`, frontmatter + markdown body) is
+ * handled by the generic reader/writer machinery. No models, no port
+ * class. 1:1 parity with Python (the descriptor file is byte-identical
+ * package data — see tests/descriptor-hash-parity.test.ts).
+ *
+ * Tier A port from the internal SDK's doc extension (s-tier-a-doc-kind);
+ * see the descriptor header for the honest subset notes.
+ */
+import type { Extension, ExtensionHost } from "../kernel/protocols.js";
+export declare class DocExtension implements Extension {
+    readonly name = "doc";
+    readonly version = "1.0.0";
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/doc.js

@@ -0,0 +1,10 @@
+import { loadDescriptors } from "../kernel/descriptor-loader.js";
+export class DocExtension {
+    name = "doc";
+    version = "1.0.0";
+    register(kernel) {
+        for (const raw of loadDescriptors(import.meta.url, "doc/kinds")) {
+            kernel.kindFromDescriptor(raw);
+        }
+    }
+}

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

@@ -0,0 +1,65 @@
+# EvalBaseline — pinned "known good" EvalRun for a suite (record plane).
+#
+# Tier B port from the internal SDK's eval extension (s-dna-eval-kit).
+# Same semantics as upstream: a pointer to one EvalRun pinned as the
+# reference for a suite; future runs are compared against it to detect
+# regressions (a case that passed in the baseline and fails now). One
+# baseline per suite by convention (`dna eval pin` names it
+# baseline-<suite>). The upstream status field (approved/candidate) did
+# not travel — a local-first workflow pins exactly one reference.
+#
+# 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-baseline
+spec:
+  target_api_version: github.com/ruinosus/dna/eval/v1
+  target_kind: EvalBaseline
+  alias: eval-eval-baseline
+  origin: github.com/ruinosus/dna/eval
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: eval-baselines
+  schema:
+    type: object
+    required:
+    - suite
+    - run_name
+    additionalProperties: false
+    properties:
+      suite:
+        type: string
+        description: Name of the EvalSuite this baseline belongs to.
+      run_name:
+        type: string
+        description: Name of the pinned EvalRun document.
+      pinned_at:
+        type: string
+        format: date-time
+      label:
+        type: string
+        description: Human note on why this run is the reference.
+  describe: '{suite} → {run_name}'
+  summary:
+    suite: ''
+    run_name: ''
+  graph_style:
+    fill: '#F59E0B'
+    stroke: '#D97706'
+    text_color: '#fff'
+  ascii_icon: 📌
+  display_label: Eval Baselines
+  docs: An EvalBaseline pins one EvalRun as the "known good" reference
+    for an EvalSuite. `dna eval run <suite> --baseline <name>` compares
+    the fresh run against the pinned run and reports regressions (passed
+    → now failing), improvements and unchanged cases — with an exit code
+    a user's CI can gate on. Pin with `dna eval pin <run>`.