dna-sdk 0.1.0

package/dist/kernel/resource.js

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Resource
+// ---------------------------------------------------------------------------
+export class Resource {
+    apiVersion;
+    kind;
+    name;
+    raw;
+    typed;
+    origin;
+    kindRef;
+    _metadataRaw;
+    _specRaw;
+    constructor(opts) {
+        this.apiVersion = opts.apiVersion;
+        this.kind = opts.kind;
+        this.name = opts.name;
+        this._metadataRaw = opts.metadata ?? {};
+        this._specRaw = opts.spec ?? {};
+        this.raw = opts.raw ?? {};
+        this.typed = opts.typed ?? null;
+        this.origin = opts.origin ?? "local";
+        this.kindRef = opts.kindRef ?? null;
+    }
+    /** Always returns Record<string, unknown> — typed metadata when available, raw dict otherwise. */
+    get metadata() {
+        if (this.typed != null &&
+            typeof this.typed === "object" &&
+            "metadata" in this.typed) {
+            return this.typed.metadata;
+        }
+        return this._metadataRaw;
+    }
+    /** Always returns Record<string, unknown> — typed spec when available, raw dict otherwise. */
+    get spec() {
+        if (this.typed != null &&
+            typeof this.typed === "object" &&
+            "spec" in this.typed) {
+            return this.typed.spec;
+        }
+        return this._specRaw;
+    }
+    /**
+     * 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() {
+        if (!this.kindRef)
+            return [];
+        const filters = this.kindRef.depFilters();
+        if (!filters)
+            return [];
+        const spec = this.spec;
+        const result = [];
+        for (const [field, targetAlias] of Object.entries(filters)) {
+            const value = spec[field];
+            let names = [];
+            if (Array.isArray(value)) {
+                names = value.filter((v) => typeof v === "string");
+            }
+            else if (typeof value === "string" && value) {
+                names = [value];
+            }
+            if (names.length === 0)
+                continue;
+            result.push({ field, targetAlias, names });
+        }
+        return result;
+    }
+    /** Create a Resource from a raw dict. */
+    static fromRaw(raw, typed, origin, kindRef) {
+        const metadata = raw.metadata ?? {};
+        return new Resource({
+            apiVersion: raw.apiVersion ?? "",
+            kind: raw.kind ?? "",
+            name: metadata.name ?? "",
+            metadata,
+            spec: raw.spec ?? {},
+            raw,
+            typed,
+            origin,
+            kindRef,
+        });
+    }
+    toString() {
+        return `Resource(${this.apiVersion}/${this.kind}: ${this.name})`;
+    }
+}

package/dist/kernel/runtime.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Runtime — public facade over Kernel.
+ *
+ * Provides the new vocabulary: storage() instead of source(),
+ * manifest() instead of instance(). Extends Kernel for full
+ * backwards compatibility during the transition.
+ */
+import { Kernel } from "./index.js";
+import type { SourcePort } from "./protocols.js";
+import type { ManifestInstance } from "./instance.js";
+export declare class Runtime extends Kernel {
+    /** Register a storage backend. Alias for source(). */
+    storage(s: SourcePort): void;
+    /** Load a manifest for a scope. Alias for instance(). */
+    manifest(scope: string, layers?: Record<string, string>): Promise<ManifestInstance>;
+}

package/dist/kernel/runtime.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime — public facade over Kernel.
+ *
+ * Provides the new vocabulary: storage() instead of source(),
+ * manifest() instead of instance(). Extends Kernel for full
+ * backwards compatibility during the transition.
+ */
+import { Kernel } from "./index.js";
+export class Runtime extends Kernel {
+    /** Register a storage backend. Alias for source(). */
+    storage(s) {
+        this.source(s);
+    }
+    /** Load a manifest for a scope. Alias for instance(). */
+    async manifest(scope, layers) {
+        return this.instance(scope, layers);
+    }
+}

package/dist/kernel/safety-scanner.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Safety scanner — Tier 1 (regex) built-in, zero deps.
+ *
+ * Detects and masks PII (CPF, CNPJ, email, phone, credit card),
+ * prompt injection, banned words, and custom regex patterns.
+ *
+ * 1:1 parity with Python dna.safety.scanner.
+ */
+export interface Violation {
+    ruleType: string;
+    entity: string;
+    text: string;
+    start: number;
+    end: number;
+    replacement: string;
+}
+export interface ScanResult {
+    found: boolean;
+    violations: Violation[];
+}
+export interface Scanner {
+    available(): boolean;
+    scan(text: string): Violation[];
+}
+export declare class RegexScanner implements Scanner {
+    private patterns;
+    constructor(rules: Array<Record<string, unknown>>);
+    available(): boolean;
+    scan(text: string): Violation[];
+    private inferTier;
+    private buildPatterns;
+}
+export declare class ScannerPipeline {
+    private scanners;
+    constructor(rules: Array<Record<string, unknown>>);
+    scan(text: string): ScanResult;
+    apply(text: string, action: string): string;
+}

package/dist/kernel/safety-scanner.js

@@ -0,0 +1,228 @@
+/**
+ * Safety scanner — Tier 1 (regex) built-in, zero deps.
+ *
+ * Detects and masks PII (CPF, CNPJ, email, phone, credit card),
+ * prompt injection, banned words, and custom regex patterns.
+ *
+ * 1:1 parity with Python dna.safety.scanner.
+ */
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+function validateCPF(cpf) {
+    const digits = cpf.replace(/\D/g, "");
+    if (digits.length !== 11)
+        return false;
+    if (/^(\d)\1{10}$/.test(digits))
+        return false;
+    let sum = 0;
+    for (let i = 0; i < 9; i++)
+        sum += parseInt(digits[i]) * (10 - i);
+    let check = 11 - (sum % 11);
+    if (check >= 10)
+        check = 0;
+    if (parseInt(digits[9]) !== check)
+        return false;
+    sum = 0;
+    for (let i = 0; i < 10; i++)
+        sum += parseInt(digits[i]) * (11 - i);
+    check = 11 - (sum % 11);
+    if (check >= 10)
+        check = 0;
+    return parseInt(digits[10]) === check;
+}
+function validateCNPJ(cnpj) {
+    const digits = cnpj.replace(/\D/g, "");
+    if (digits.length !== 14)
+        return false;
+    const weights1 = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+    const weights2 = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+    let sum = 0;
+    for (let i = 0; i < 12; i++)
+        sum += parseInt(digits[i]) * weights1[i];
+    let check = sum % 11 < 2 ? 0 : 11 - (sum % 11);
+    if (parseInt(digits[12]) !== check)
+        return false;
+    sum = 0;
+    for (let i = 0; i < 13; i++)
+        sum += parseInt(digits[i]) * weights2[i];
+    check = sum % 11 < 2 ? 0 : 11 - (sum % 11);
+    return parseInt(digits[13]) === check;
+}
+function maskKeepFormat(text, visibleEnd = 2) {
+    const digits = text.replace(/\D/g, "");
+    let idx = 0;
+    return text.replace(/\d/g, () => {
+        const d = idx++;
+        return d >= digits.length - visibleEnd ? digits[d] : "*";
+    });
+}
+const PII_PATTERNS = {
+    cpf: {
+        entity: "cpf",
+        regex: /\d{3}\.?\d{3}\.?\d{3}-?\d{2}/g,
+        maskFn: (m) => maskKeepFormat(m, 0),
+        validate: validateCPF,
+    },
+    cnpj: {
+        entity: "cnpj",
+        regex: /\d{2}\.?\d{3}\.?\d{3}\/?\d{4}-?\d{2}/g,
+        maskFn: (m) => maskKeepFormat(m, 0),
+        validate: validateCNPJ,
+    },
+    email: {
+        entity: "email",
+        regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+        maskFn: (m) => {
+            const [local, domain] = m.split("@");
+            return `${local[0]}***@${domain}`;
+        },
+    },
+    phone: {
+        entity: "phone",
+        regex: /\+?\d{1,3}[\s.-]?\(?\d{2,3}\)?[\s.-]?\d{4,5}[\s.-]?\d{4}/g,
+        maskFn: (m) => maskKeepFormat(m, 4),
+    },
+    credit_card: {
+        entity: "credit_card",
+        regex: /\d{4}[\s.-]?\d{4}[\s.-]?\d{4}[\s.-]?\d{4}/g,
+        maskFn: (m) => {
+            const d = m.replace(/\D/g, "");
+            return `****-****-****-${d.slice(-4)}`;
+        },
+    },
+};
+// ---------------------------------------------------------------------------
+// RegexScanner — Tier 1, built-in, zero deps
+// ---------------------------------------------------------------------------
+export class RegexScanner {
+    patterns;
+    constructor(rules) {
+        this.patterns = [];
+        for (const rule of rules) {
+            if (rule.type !== "pii" &&
+                rule.type !== "prompt_injection" &&
+                rule.type !== "banned_words" &&
+                rule.type !== "custom_regex")
+                continue;
+            const tier = rule.tier ?? this.inferTier(rule);
+            if (tier !== "regex")
+                continue;
+            this.patterns.push(...this.buildPatterns(rule));
+        }
+    }
+    available() {
+        return true;
+    }
+    scan(text) {
+        const violations = [];
+        for (const { entity, regex, maskFn, validate } of this.patterns) {
+            // Create fresh regex to reset lastIndex
+            const re = new RegExp(regex.source, regex.flags);
+            let match;
+            while ((match = re.exec(text)) !== null) {
+                if (validate && !validate(match[0]))
+                    continue;
+                violations.push({
+                    ruleType: "pii",
+                    entity,
+                    text: match[0],
+                    start: match.index,
+                    end: match.index + match[0].length,
+                    replacement: maskFn(match[0]),
+                });
+            }
+        }
+        return violations;
+    }
+    inferTier(rule) {
+        if (rule.type === "pii") {
+            const entities = rule.entities ?? [];
+            if (entities.some((e) => ["person", "location"].includes(e)))
+                return "ml";
+            return "regex";
+        }
+        return "regex";
+    }
+    buildPatterns(rule) {
+        const patterns = [];
+        if (rule.type === "pii") {
+            const entities = rule.entities ?? [];
+            for (const entity of entities) {
+                const p = PII_PATTERNS[entity];
+                if (p)
+                    patterns.push(p);
+            }
+        }
+        if (rule.type === "prompt_injection") {
+            patterns.push({
+                entity: "prompt_injection",
+                regex: /\b(ignore\s+(previous|above|all)\s+(instructions?|rules?|prompts?)|system\s+prompt|jailbreak|DAN\s+mode)\b/gi,
+                maskFn: () => "[BLOCKED]",
+            });
+        }
+        if (rule.type === "banned_words") {
+            const words = rule.words ?? [];
+            if (words.length > 0) {
+                const escaped = words.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+                patterns.push({
+                    entity: "banned_word",
+                    regex: new RegExp(`\\b(${escaped.join("|")})\\b`, "gi"),
+                    maskFn: () => "[REDACTED]",
+                });
+            }
+        }
+        if (rule.type === "custom_regex") {
+            const regexPatterns = rule.patterns ?? [];
+            for (const p of regexPatterns) {
+                try {
+                    patterns.push({
+                        entity: "custom",
+                        regex: new RegExp(p, "g"),
+                        maskFn: () => "[REDACTED]",
+                    });
+                }
+                catch {
+                    /* invalid regex — skip */
+                }
+            }
+        }
+        return patterns;
+    }
+}
+// ---------------------------------------------------------------------------
+// ScannerPipeline
+// ---------------------------------------------------------------------------
+export class ScannerPipeline {
+    scanners;
+    constructor(rules) {
+        this.scanners = [new RegexScanner(rules)];
+        // Tier 2/3/4 would be added here if available
+    }
+    scan(text) {
+        const violations = [];
+        for (const scanner of this.scanners) {
+            if (scanner.available())
+                violations.push(...scanner.scan(text));
+        }
+        return { found: violations.length > 0, violations };
+    }
+    apply(text, action) {
+        const result = this.scan(text);
+        if (!result.found)
+            return text;
+        if (action === "block") {
+            throw new Error(`SafetyPolicy violation: ${result.violations.map((v) => v.entity).join(", ")}`);
+        }
+        if (action === "mask") {
+            // Sort violations by position descending to replace from end to start
+            const sorted = [...result.violations].sort((a, b) => b.start - a.start);
+            let masked = text;
+            for (const v of sorted) {
+                masked = masked.slice(0, v.start) + v.replacement + masked.slice(v.end);
+            }
+            return masked;
+        }
+        return text; // log: no modification
+    }
+}

package/dist/kernel/serialize-to-files.d.ts

@@ -0,0 +1,29 @@
+import type { Kernel } from "./index.js";
+/**
+ * A single file emitted by a document serializer. Re-exports the
+ * canonical shape from protocols.ts (L3 2026-05-25: now accepts
+ * `contentBytes?: Uint8Array` for binary entries alongside `content`).
+ *
+ * `relativePath` is relative to the manifest scope directory. The file-based
+ * adapter composing this helper is responsible for prefixing `<baseDir>/<scope>/`
+ * when it writes to disk.
+ */
+export type { SerializedFile } from "./protocols.js";
+import type { SerializedFile as _SerializedFile } from "./protocols.js";
+/**
+ * Turn a raw document into the files a file-based adapter should write.
+ *
+ * Pure computation — no I/O, no mutation of `raw`. Adapters compose this
+ * with their filesystem I/O (TauriWritableSource, FilesystemWritableSource
+ * when it ports to TS, etc.).
+ *
+ * Internally delegates to `kernel.serializeDocument`, which already
+ * encapsulates the Kind/Writer lookup + StorageDescriptor path prefixing.
+ * Extracting this as a named helper is a contract move: adapters should
+ * import `serializeRawToFiles`, not reach into the Kernel's internals.
+ *
+ * The scope argument is intentionally NOT exposed here — scope is a
+ * path-prefix concern the ADAPTER applies. `serializeDocument` treats it
+ * as "" internally, so paths come back relative to the scope root.
+ */
+export declare function serializeRawToFiles(raw: Record<string, unknown>, kernel: Kernel): readonly _SerializedFile[];

package/dist/kernel/serialize-to-files.js

@@ -0,0 +1,23 @@
+/**
+ * Turn a raw document into the files a file-based adapter should write.
+ *
+ * Pure computation — no I/O, no mutation of `raw`. Adapters compose this
+ * with their filesystem I/O (TauriWritableSource, FilesystemWritableSource
+ * when it ports to TS, etc.).
+ *
+ * Internally delegates to `kernel.serializeDocument`, which already
+ * encapsulates the Kind/Writer lookup + StorageDescriptor path prefixing.
+ * Extracting this as a named helper is a contract move: adapters should
+ * import `serializeRawToFiles`, not reach into the Kernel's internals.
+ *
+ * The scope argument is intentionally NOT exposed here — scope is a
+ * path-prefix concern the ADAPTER applies. `serializeDocument` treats it
+ * as "" internally, so paths come back relative to the scope root.
+ */
+export function serializeRawToFiles(raw, kernel) {
+    const scope = "";
+    const kind = String(raw.kind ?? "");
+    const name = String((raw.metadata ?? {}).name ?? "");
+    const payload = kernel.serializeDocument(scope, kind, name, raw);
+    return payload.files;
+}

package/dist/kernel/spec-access.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generic accessors for Document.spec — lets consumers read fields without
+ * knowing the kind's typed model. Returns undefined / [] / {} for missing
+ * fields; throws a clear error on type mismatch (wrong field type in the
+ * actual doc).
+ *
+ * Use these in extension code, renderers, and tools that operate across
+ * many kinds. For single-kind code that already branched on kind, using
+ * the typed model via `doc.typed` is fine.
+ */
+import type { Document } from "./document.js";
+export declare function readSpecString(doc: Document | {
+    spec?: Record<string, unknown>;
+}, field: string): string | undefined;
+export declare function readSpecStringArray(doc: Document | {
+    spec?: Record<string, unknown>;
+}, field: string): string[];
+export declare function readSpecRecord(doc: Document | {
+    spec?: Record<string, unknown>;
+}, field: string): Record<string, unknown>;
+export declare function readSpecRecordArray(doc: Document | {
+    spec?: Record<string, unknown>;
+}, field: string): Record<string, unknown>[];

package/dist/kernel/spec-access.js

@@ -0,0 +1,40 @@
+function getSpec(doc) {
+    const spec = doc.spec;
+    return (spec && typeof spec === "object") ? spec : {};
+}
+export function readSpecString(doc, field) {
+    const v = getSpec(doc)[field];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "string") {
+        throw new TypeError(`spec['${field}']: expected string, got ${typeof v}`);
+    }
+    return v;
+}
+export function readSpecStringArray(doc, field) {
+    const v = getSpec(doc)[field];
+    if (v === undefined || v === null)
+        return [];
+    if (!Array.isArray(v)) {
+        throw new TypeError(`spec['${field}']: expected array, got ${typeof v}`);
+    }
+    return v;
+}
+export function readSpecRecord(doc, field) {
+    const v = getSpec(doc)[field];
+    if (v === undefined || v === null)
+        return {};
+    if (typeof v !== "object" || Array.isArray(v)) {
+        throw new TypeError(`spec['${field}']: expected object, got ${typeof v}`);
+    }
+    return v;
+}
+export function readSpecRecordArray(doc, field) {
+    const v = getSpec(doc)[field];
+    if (v === undefined || v === null)
+        return [];
+    if (!Array.isArray(v)) {
+        throw new TypeError(`spec['${field}']: expected array, got ${typeof v}`);
+    }
+    return v;
+}

package/dist/kernel/studio_ui.d.ts

@@ -0,0 +1,88 @@
+/**
+ * StudioUIMetadata — UI declarations attached to a KindPort.
+ *
+ * Net-new TS twin of Python `dna.kernel.studio_ui.StudioUIMetadata`
+ * (studio_ui.py:54-215), added for the descriptor-expressiveness `ui:` field
+ * (spec 2026-06-11 D1). Reverses the previously-documented posture that `ui`
+ * was "a Studio-backend concern… intentionally not mirrored"
+ * (src/extensions/audit.ts) — byte-parity of `.kind.yaml` descriptors across
+ * runtimes requires BOTH the Python and the TS DeclarativeKindPort to parse the
+ * same `ui:` block into the same data and serialize it identically.
+ *
+ * Field-for-field mirror + `toDict()` (same omission rules as Python
+ * `to_dict()`) + `resolveLabel()` (same i18n fallback order as Python
+ * `resolve_label()`). There is no TS class golden for `ui` (TS Kind classes
+ * never carried it); the parity pin is structural — `toDict()` parity with
+ * Python via the shared fixture tests/fixtures/studio-ui-parity.json.
+ */
+/** Studio mode this Kind primarily belongs to. */
+export type ModeId = "plan" | "build" | "quality" | "govern" | "cognitive";
+/** CRUD action a route serves. */
+export type UIAction = "list" | "detail" | "edit" | "create";
+/** Locale → translated string. e.g. {en: 'Eval Cases', 'pt-BR': 'Casos'}. */
+export type LabelI18n = Record<string, string>;
+/**
+ * Canonical, ordered set of StudioUIMetadata field names. Single source of
+ * truth — `KindDefinitionSpec.from_raw`/zod validate `ui:` keys against THIS
+ * list (no second hardcoded list). Mirrors the Python dataclass field order.
+ */
+export declare const UI_METADATA_FIELDS: readonly ["mode", "in_sidebar", "display_order", "label", "icon", "description", "breadcrumb", "routes", "permissions", "note", "feature_flag"];
+export type UIMetadataField = (typeof UI_METADATA_FIELDS)[number];
+/** Constructor input — every field optional, mirroring the Python dataclass
+ *  defaults (no mode, no sidebar, display_order 100, all others None/empty). */
+export interface StudioUIMetadataInit {
+    mode?: ModeId | null;
+    in_sidebar?: boolean;
+    display_order?: number;
+    label?: string | LabelI18n | null;
+    icon?: string | null;
+    description?: string | LabelI18n | null;
+    breadcrumb?: string[] | null;
+    routes?: Record<string, string>;
+    permissions?: Record<string, string[] | string>;
+    note?: string | null;
+    feature_flag?: string | null;
+}
+/**
+ * UI declarations for a Kind, consumed by Studio's manifest. Defaults are
+ * conservative: no mode, no sidebar, no routes — the Kind is invisible in
+ * Studio unless explicitly opted in. 1:1 with Python `StudioUIMetadata`.
+ */
+export declare class StudioUIMetadata {
+    readonly mode: ModeId | null;
+    readonly in_sidebar: boolean;
+    readonly display_order: number;
+    readonly label: string | LabelI18n | null;
+    readonly icon: string | null;
+    readonly description: string | LabelI18n | null;
+    readonly breadcrumb: string[] | null;
+    readonly routes: Record<string, string>;
+    readonly permissions: Record<string, string[] | string>;
+    readonly note: string | null;
+    readonly feature_flag: string | null;
+    constructor(init?: StudioUIMetadataInit);
+    /** The canonical field-name set (single source of truth for `ui:` validation). */
+    static fields(): readonly UIMetadataField[];
+    /**
+     * Serialize for the /kinds/manifest JSON response. Omits None/empty fields
+     * so the wire payload stays small — EXACTLY the Python `to_dict()` omission
+     * rules (studio_ui.py:161-192):
+     *   - mode: only if not null
+     *   - in_sidebar: only if true
+     *   - display_order: only if !== 100
+     *   - label/icon/description/note/feature_flag: only if not null
+     *   - breadcrumb: only if not null (an empty list IS kept, like Python)
+     *   - routes/permissions: only if non-empty
+     */
+    toDict(): Record<string, unknown>;
+    /**
+     * Resolve i18n label for the requested locale. Fallback order (mirrors
+     * Python `resolve_label`):
+     *   1. Exact locale match (e.g. 'pt-BR').
+     *   2. Language-only fallback (e.g. 'pt' from 'pt-BR').
+     *   3. 'en' (project default).
+     *   4. null.
+     * A plain-string label is returned as-is regardless of locale.
+     */
+    resolveLabel(locale?: string): string | null;
+}