dna-sdk 0.1.0

package/dist/extensions/audit.js

@@ -0,0 +1,62 @@
+import { KindBase } from "../kernel/kind_base.js";
+import { SD } from "../kernel/protocols.js";
+import { loadDescriptors } from "../kernel/descriptor-loader.js";
+const API_VERSION = "github.com/ruinosus/dna/audit/v1";
+const ORIGIN = "github.com/ruinosus/dna/audit";
+// ---------------------------------------------------------------------------
+// UserRoleAssignmentKind
+// ---------------------------------------------------------------------------
+class UserRoleAssignmentKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "UserRoleAssignment";
+    alias = "audit-userroleassignment";
+    origin = ORIGIN;
+    isPromptTarget = false;
+    isRuntimeArtifact = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.yaml("user-roles");
+    graphStyle = { fill: "#6366f1", stroke: "#4f46e5", textColor: "#fff" };
+    asciiIcon = "👥";
+    displayLabel = "User Role";
+    docs = "Persistent role assignment for a user inside a tenant. The doc name IS the " +
+        "user_id. Roles list is the source of truth for require_role decorators when " +
+        "Clerk webhook sync is enabled.";
+    dependencies() { return null; }
+    summary() { return null; }
+    schema() {
+        return {
+            type: "object",
+            required: ["user_id", "roles", "updated_at"],
+            additionalProperties: true,
+            properties: {
+                user_id: { type: "string", description: "Identity claim (sub or email)." },
+                email: { type: "string" },
+                roles: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Authoritative role list. Backend require_role reads claims.roles " +
+                        "which is set by Clerk via JWT — this Kind is the admin-managed " +
+                        "mirror for Clerk's org membership.",
+                },
+                note: { type: "string", description: "Free-form admin note (hire date, etc)." },
+                updated_at: { type: "string", format: "date-time" },
+            },
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export class AuditExtension {
+    name = "audit";
+    version = "1.0.0";
+    register(kernel) {
+        kernel.kind(new UserRoleAssignmentKind());
+        // expr batch A: AuditLog as a descriptor — kinds/*.kind.yaml package data
+        // registered through the SAME funnel as per-scope KindDefinitions.
+        for (const raw of loadDescriptors(import.meta.url, "audit/kinds")) {
+            kernel.kindFromDescriptor(raw);
+        }
+    }
+}

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

@@ -0,0 +1,296 @@
+# Automation — unified declarative background automation (record plane).
+#
+# Tier A port from the internal SDK's automation extension
+# (s-tier-a-automation). Upstream, one Automation doc REPLACED a trio of
+# structurally-identical Kinds (async-tool job / bus-event hook / cron
+# schedule) with a single superset schema discriminated by ``on.type`` —
+# the piece that killed hardcoded dispatch: adding or retargeting an
+# automation is writing one YAML, zero deploy. What travels is the
+# DECLARATION: the Kind, its validation and the query helpers
+# (``dna.extensions.automation.query``). EXECUTION does not travel — the
+# SDK has no scheduler/bus/worker; the host reads Automation docs via the
+# query helpers and runs them (extension point documented in
+# docs/concepts/builtin-kinds.md, same declare-here/execute-in-the-host
+# pattern as the CLI's register_post_transition_hook).
+#
+# Trigger vocabulary (honest evolution of the upstream discriminator):
+#   - cron — 5-field cron expression; the write guard
+#     (dna/extensions/automation/write_guards.py + TS twin) parses it at
+#     write time (zero-dep validator, no name aliases like JAN/MON).
+#   - hook — a kernel lifecycle hook name; upstream's free-form bus-event
+#     trigger becomes the kernel's OWN typed vocabulary (KNOWN_HOOK_NAMES,
+#     s-dna-typed-hook-names) and the write guard vetoes unknown names.
+#   - tool — an async dispatch tool the host exposes to the model
+#     (tool_name + declared input_schema + primary_input).
+#
+# Deliberately NOT ported (coupled to the upstream product, not the Kind):
+#   - ``on.condition: shallow_scope`` + ``on.window_minutes`` — cognitive-
+#     autopilot gating with no DNA equivalent;
+#   - runner kind ``engine`` — upstream cognitive engines; DNA runners are
+#     the real Kinds Agent (kind=agent) and Tool (kind=tool).
+#
+# tenant_scope intentionally NOT declared — permissive (base + per-tenant
+# overlay). Automation is an inheritable `_lib` default (it is already in
+# DEFAULT_INHERITABLE_KINDS_V1); the máxima "inheritable ⇒ never TENANTED"
+# applies (test_inheritable_kinds_tenancy.py).
+#
+# PARITY-CRITICAL package data: byte-identical mirror under both runtimes'
+# automation/kinds/ (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: automation
+spec:
+  target_api_version: github.com/ruinosus/dna/automation/v1
+  target_kind: Automation
+  alias: dna-automation
+  origin: github.com/ruinosus/dna/automation
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: automations
+  spec_defaults:
+    enabled: true
+  schema:
+    type: object
+    required:
+    - 'on'
+    - runner
+    additionalProperties: false
+    properties:
+      'on':
+        type: object
+        required:
+        - type
+        additionalProperties: false
+        description: The trigger. type=cron → scheduled (5-field cron
+          expression, validated at write); type=hook → a kernel lifecycle
+          hook name (KNOWN_HOOK_NAMES vocabulary, validated at write);
+          type=tool → an async dispatch tool the host exposes to the model.
+        properties:
+          type:
+            type: string
+            enum:
+            - cron
+            - hook
+            - tool
+          cron:
+            type: string
+            description: 5-field cron 'min hour dom mon dow', e.g.
+              '0 10 * * 1,3,5'. Parsed at write time by the automation
+              write guard (numeric fields, '*', ranges, lists, steps —
+              no JAN/MON name aliases).
+          hook:
+            type: string
+            description: Kernel lifecycle hook that fires this automation,
+              e.g. 'post_save' or 'post_build_prompt'. Must be one of the
+              kernel's KNOWN_HOOK_NAMES — the write guard vetoes unknown
+              names.
+          tool_name:
+            type: string
+            description: The dispatch tool the model sees (e.g.
+              deep_research_async).
+          input_schema:
+            type: array
+            description: Declared args of the dispatch tool (all strings).
+            items:
+              type: object
+              required:
+              - name
+              additionalProperties: true
+              properties:
+                name:
+                  type: string
+                type:
+                  type: string
+                description:
+                  type: string
+                required:
+                  type: boolean
+                default:
+                  type: string
+          primary_input:
+            type: string
+            description: Which input arg carries the main user content fed
+              to an agent runner. Defaults to the first input_schema entry.
+        allOf:
+        - if:
+            properties:
+              type:
+                const: cron
+            required:
+            - type
+          then:
+            required:
+            - cron
+        - if:
+            properties:
+              type:
+                const: hook
+            required:
+            - type
+          then:
+            required:
+            - hook
+        - if:
+            properties:
+              type:
+                const: tool
+            required:
+            - type
+          then:
+            required:
+            - tool_name
+      runner:
+        type: object
+        required:
+        - kind
+        - ref
+        additionalProperties: false
+        properties:
+          kind:
+            type: string
+            enum:
+            - agent
+            - tool
+          ref:
+            type: string
+            description: Agent name (kind=agent) or Tool name (kind=tool)
+              that executes the automation.
+          model:
+            type: string
+            description: Optional model override for the runner.
+          expected_output:
+            type: string
+            enum:
+            - slug
+            - json
+            - text
+            description: For an agent runner, what the agent should
+              produce. 'slug' = persist a real domain doc (result_kind) and
+              return its slug; 'text'/'json' = return prose/structured
+              output inline. Hosts default to 'text'.
+          timeout_seconds:
+            type: number
+            description: Wall-clock budget the host should give one run.
+      agent_directive:
+        type: string
+        description: Dispatch instruction sent to an agent runner (with
+          {arg} placeholders). Optional — a tool runner needs none.
+      input:
+        type: object
+        additionalProperties: true
+        description: Structured input the host resolves into the runner's
+          context. Hosts may support tokens such as {scope}, {now},
+          {utc_date}.
+      result_kind:
+        type: string
+        description: Kind the automation output should be persisted as
+          (e.g. Research, Doc) when the runner produces a document.
+      result_spec_template:
+        type: object
+        additionalProperties: true
+        description: Deterministic persist template — when an agent runner
+          synthesizes but does not persist a doc itself, the host creates a
+          result_kind doc from this template ({arg} fills from the args,
+          {output} from the agent synthesis).
+      running_message:
+        type: string
+        description: Spoken/UI copy returned at dispatch (tool trigger).
+      done_message:
+        type: string
+        description: Spoken/UI copy attached to the finished run. Supports
+          {placeholders} from the args.
+      enabled:
+        type: boolean
+        description: Disabled automations stay declared but hosts must not
+          fire them (automations_for filters them out by default).
+      description:
+        type: string
+      labels:
+        type: array
+        items:
+          type: string
+      safety:
+        type: object
+        additionalProperties: false
+        description: Loop-safety the HOST enforces for this automation. All
+          fields optional — an absent field falls back to the host default.
+        properties:
+          debounce_seconds:
+            type: number
+            minimum: 0
+            description: Coalesce repeated fires within this window into
+              one.
+          cooldown_minutes:
+            type: integer
+            minimum: 0
+            description: Do not re-fire for the same scope within this
+              wall-clock window.
+          max_fires_per_minute:
+            type: integer
+            minimum: 1
+            description: Circuit-breaker rate cap per (scope, automation).
+          max_fan_out:
+            type: integer
+            minimum: 1
+            description: Cap on documents one fire may produce.
+          idempotency_key:
+            type: string
+            description: Template, e.g. '{scope}:{utc_date}'. A 2nd fire
+              with the same resolved key is a no-op.
+  describe:
+    path: description
+  description_fallback_field: description
+  summary:
+    on_type:
+      path: on.type
+    trigger:
+      paths:
+      - on.cron
+      - on.hook
+      - on.tool_name
+      filter_falsy: true
+    runner_kind:
+      path: runner.kind
+      default: ''
+    runner_ref:
+      path: runner.ref
+      default: ''
+    enabled: true
+  ui:
+    mode: build
+    label:
+      en: Automations
+      pt-BR: Automações
+    icon: ⚙️
+    description:
+      en: 'Unified declarative automation: cron/hook/tool trigger + runner.'
+      pt-BR: 'Automação declarativa unificada: gatilho cron/hook/tool + runner.'
+    routes:
+      list: docs/Automation
+      detail: docs/Automation/:name
+    permissions:
+      list: any
+      detail: any
+    in_sidebar: true
+    display_order: 54
+  graph_style:
+    fill: '#60A5FA'
+    stroke: '#2563EB'
+    text_color: '#fff'
+  ascii_icon: ⚙️
+  display_label: Automations
+  docs: An Automation declares background work as data — ``on`` picks the
+    trigger (cron = 5-field schedule; hook = a kernel lifecycle hook name
+    from KNOWN_HOOK_NAMES; tool = an async dispatch tool the host exposes
+    to the model), ``runner`` picks what executes (an Agent or a Tool by
+    name), plus the shared agent_directive / input / result templating /
+    spoken copy / safety block. Adding or retargeting an automation is
+    writing one YAML, zero deploy. The SDK validates and lists (see
+    ``dna.extensions.automation.query.automations_for``); the HOST
+    executes — the runner contract is an extension point, documented in
+    docs/concepts/builtin-kinds.md.

package/dist/extensions/automation/query.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Query helpers a host executor uses to read Automation docs.
+ *
+ * The SDK declares and validates automations; the HOST executes them (see
+ * docs/concepts/builtin-kinds.md — the execution extension point). These
+ * helpers are the read side of that contract, built strictly on the
+ * blessed instance query surface (`instance.all`): no kernel method is
+ * added — listing automations is extension domain knowledge, not
+ * microkernel surface.
+ *
+ * Usage (host executor):
+ *
+ *   const mi = await kernel.instance("my-scope");
+ *   for (const doc of automationsFor(mi, "cron")) {
+ *     schedule(triggerKey(doc), doc.spec.runner, doc.spec);
+ *   }
+ *
+ * 1:1 parity with Python `dna.extensions.automation.query`.
+ */
+import type { Document } from "../../kernel/document.js";
+/** The `on.type` discriminator vocabulary (mirrors the descriptor enum). */
+export declare const TRIGGER_TYPES: readonly ["cron", "hook", "tool"];
+export type TriggerType = (typeof TRIGGER_TYPES)[number];
+/** The narrow instance surface the helpers read through. */
+interface QueryableInstance {
+    all(kind: string): Document[];
+}
+/**
+ * List the scope's Automation docs, filtered for a host executor.
+ *
+ * - `triggerType` — keep only automations whose `on.type` matches
+ *   (`"cron"` / `"hook"` / `"tool"`); `null`/omitted returns all.
+ * - `enabledOnly` (default true) — drop docs with `enabled: false`
+ *   (declared but paused; hosts must not fire them).
+ *
+ * `instance` is a `ManifestInstance` — the blessed query surface. Source
+ * order is preserved (inherited `_lib` defaults resolve like any other
+ * Kind; a tenant overlay wins per the layer policy).
+ */
+export declare function automationsFor(instance: QueryableInstance, triggerType?: TriggerType | null, opts?: {
+    enabledOnly?: boolean;
+}): Document[];
+/**
+ * The trigger's identifying value: the cron expression (`cron`), the
+ * hook name (`hook`) or the dispatch tool name (`tool`). Null when the
+ * trigger is missing/unknown.
+ */
+export declare function triggerKey(doc: Document): string | null;
+export {};

package/dist/extensions/automation/query.js

@@ -0,0 +1,77 @@
+/**
+ * Query helpers a host executor uses to read Automation docs.
+ *
+ * The SDK declares and validates automations; the HOST executes them (see
+ * docs/concepts/builtin-kinds.md — the execution extension point). These
+ * helpers are the read side of that contract, built strictly on the
+ * blessed instance query surface (`instance.all`): no kernel method is
+ * added — listing automations is extension domain knowledge, not
+ * microkernel surface.
+ *
+ * Usage (host executor):
+ *
+ *   const mi = await kernel.instance("my-scope");
+ *   for (const doc of automationsFor(mi, "cron")) {
+ *     schedule(triggerKey(doc), doc.spec.runner, doc.spec);
+ *   }
+ *
+ * 1:1 parity with Python `dna.extensions.automation.query`.
+ */
+const KIND = "Automation";
+/** The `on.type` discriminator vocabulary (mirrors the descriptor enum). */
+export const TRIGGER_TYPES = ["cron", "hook", "tool"];
+function specOf(doc) {
+    const spec = doc.spec;
+    return typeof spec === "object" && spec !== null && !Array.isArray(spec)
+        ? spec
+        : {};
+}
+function onOf(spec) {
+    const on = spec.on;
+    return typeof on === "object" && on !== null && !Array.isArray(on)
+        ? on
+        : {};
+}
+/**
+ * List the scope's Automation docs, filtered for a host executor.
+ *
+ * - `triggerType` — keep only automations whose `on.type` matches
+ *   (`"cron"` / `"hook"` / `"tool"`); `null`/omitted returns all.
+ * - `enabledOnly` (default true) — drop docs with `enabled: false`
+ *   (declared but paused; hosts must not fire them).
+ *
+ * `instance` is a `ManifestInstance` — the blessed query surface. Source
+ * order is preserved (inherited `_lib` defaults resolve like any other
+ * Kind; a tenant overlay wins per the layer policy).
+ */
+export function automationsFor(instance, triggerType = null, opts = {}) {
+    const enabledOnly = opts.enabledOnly ?? true;
+    if (triggerType !== null && !TRIGGER_TYPES.includes(triggerType)) {
+        throw new Error(`unknown triggerType ${JSON.stringify(triggerType)} — expected one ` +
+            `of ${JSON.stringify(TRIGGER_TYPES)}`);
+    }
+    const out = [];
+    for (const doc of instance.all(KIND)) {
+        const spec = specOf(doc);
+        const on = onOf(spec);
+        if (triggerType !== null && on.type !== triggerType)
+            continue;
+        if (enabledOnly && spec.enabled === false)
+            continue;
+        out.push(doc);
+    }
+    return out;
+}
+/**
+ * The trigger's identifying value: the cron expression (`cron`), the
+ * hook name (`hook`) or the dispatch tool name (`tool`). Null when the
+ * trigger is missing/unknown.
+ */
+export function triggerKey(doc) {
+    const on = onOf(specOf(doc));
+    const pick = on.type === "cron" ? on.cron
+        : on.type === "hook" ? on.hook
+            : on.type === "tool" ? on.tool_name
+                : null;
+    return typeof pick === "string" ? pick : null;
+}

package/dist/extensions/automation/write-guards.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 type { PreSaveContext } from "../../kernel/hooks.js";
+export declare const PRIORITY_TRIGGER_GUARD = 50;
+/**
+ * Validate a 5-field cron expression. Throws on the first problem
+ * (didactic message); returns void when valid.
+ */
+export declare function validateCronExpression(expr: string): void;
+/**
+ * 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 declare function automationTriggerGuard(ctx: PreSaveContext): void;
+/**
+ * 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 declare function registerWriteGuards(kernel: unknown): void;