dna-sdk 0.1.0

package/dist/kernel/document.js

@@ -0,0 +1,71 @@
+/**
+ * Document — unified wrapper for all manifest documents.
+ *
+ * 1:1 parity with Python dna.v3.kernel.document.
+ *
+ * v1.0 — `Document<SpecT>` generic typing. Consumers can declare
+ * spec type at the call site without a runtime cost:
+ *
+ *     const doc = mi.documents.find((d) => d.kind === "Asset" && d.name === "x") as Document<AssetSpec>;
+ *     doc.spec.summary?.byte_count;  // type-checker validated
+ *
+ * Bare `Document` defaults to `Record<string, unknown>` so existing
+ * untyped code continues working. Purely additive — no API change
+ * for callers that don't opt in.
+ */
+export class Document {
+    apiVersion;
+    kind;
+    name;
+    raw;
+    typed;
+    origin;
+    _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";
+    }
+    /** 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;
+    }
+    /** Returns the spec, typed as `SpecT` when consumers parameterize
+     *  the Document. Runtime: still a plain dict. */
+    get spec() {
+        if (this.typed != null &&
+            typeof this.typed === "object" &&
+            "spec" in this.typed) {
+            return this.typed.spec;
+        }
+        return this._specRaw;
+    }
+    /** Create a Document from a raw dict. */
+    static fromRaw(raw, typed, origin) {
+        const metadata = raw.metadata ?? {};
+        return new Document({
+            apiVersion: raw.apiVersion ?? "",
+            kind: raw.kind ?? "",
+            name: metadata.name ?? "",
+            metadata,
+            spec: raw.spec ?? {},
+            raw,
+            typed,
+            origin,
+        });
+    }
+    toString() {
+        return `Document(${this.apiVersion}/${this.kind}: ${this.name})`;
+    }
+}

package/dist/kernel/embedding.d.ts

@@ -0,0 +1,28 @@
+import type { EmbeddingPort } from "./protocols.js";
+/**
+ * Default dimensionality of the fake space. Matches all-MiniLM-L6-v2 (the real
+ * ONNX provider) so swapping providers keeps the vector length — and any
+ * downstream vector-store column width — stable.
+ */
+export declare const FAKE_EMBEDDING_DIMS = 384;
+/**
+ * Stable identity of this embedding space. Versioned so a future change to the
+ * hashing scheme is a NEW space (old vectors stay honestly incomparable).
+ */
+export declare const FAKE_EMBEDDING_MODEL_ID = "dna-fake-hash-v1";
+/**
+ * Deterministic, L2-normalized hash embedding of a single string. Bit-identical
+ * to the Python `fake_embed_one`. Empty/tokenless text → all-zeros (an all-zero
+ * vector is honestly "no signal", never normalized).
+ */
+export declare function fakeEmbedOne(text: string, dims?: number): number[];
+/**
+ * Zero-dependency `EmbeddingPort` — the offline/CI default. Structurally
+ * satisfies `EmbeddingPort` (`modelId`, `dims`, async `embed`).
+ */
+export declare class FakeEmbeddingProvider implements EmbeddingPort {
+    readonly modelId = "dna-fake-hash-v1";
+    readonly dims: number;
+    constructor(dims?: number);
+    embed(texts: string[]): Promise<number[][]>;
+}

package/dist/kernel/embedding.js

@@ -0,0 +1,78 @@
+/**
+ * Deterministic hash-based embedding — the zero-dependency offline floor.
+ *
+ * TypeScript twin of `dna/kernel/embedding.py`. This is the default
+ * `EmbeddingPort` the kernel falls back to when no real provider (e.g. the
+ * optional ONNX all-MiniLM-L6-v2 adapter) is registered. It is NOT a semantic
+ * embedder — it is a stable, content-addressed vector so the search plane and
+ * its tests have *something* deterministic to run against in CI and offline,
+ * without pulling any ML dependency.
+ *
+ * Parity contract (rsh-memory-similarity-evolution → rec-embedding-port): this
+ * produces the BIT-IDENTICAL vector to the Python `fake_embed_one` for the same
+ * string — guaranteed *by construction*:
+ *
+ *   1. Tokenization is `[a-z0-9]+` over the lower-cased text — identical token
+ *      lists in TS (`String.match`) and Py (`re.findall`) for ASCII input.
+ *   2. Each token is hashed with SHA-256 (`js-sha256` / stdlib `hashlib`); the
+ *      first 4 bytes pick a dimension (big-endian uint32 mod `dims`) and the
+ *      5th byte's low bit picks a sign (±1). Accumulation is INTEGER, so the
+ *      pre-normalization vector is exact on both sides regardless of order.
+ *   3. L2-normalization divides each integer component by `sqrt(sum(cᵢ²))`.
+ *      The sum-of-squares is an exact integer; `sqrt` and division are both
+ *      IEEE-754 correctly-rounded, so the resulting doubles are bit-identical.
+ *
+ * The golden fixture `tests/parity-fixtures/fake-embedding-golden.json` pins a
+ * handful of strings to their exact vectors; both language suites assert
+ * against it.
+ */
+import { sha256 } from "js-sha256";
+/**
+ * Default dimensionality of the fake space. Matches all-MiniLM-L6-v2 (the real
+ * ONNX provider) so swapping providers keeps the vector length — and any
+ * downstream vector-store column width — stable.
+ */
+export const FAKE_EMBEDDING_DIMS = 384;
+/**
+ * Stable identity of this embedding space. Versioned so a future change to the
+ * hashing scheme is a NEW space (old vectors stay honestly incomparable).
+ */
+export const FAKE_EMBEDDING_MODEL_ID = "dna-fake-hash-v1";
+const TOKEN_RE = /[a-z0-9]+/g;
+/**
+ * Deterministic, L2-normalized hash embedding of a single string. Bit-identical
+ * to the Python `fake_embed_one`. Empty/tokenless text → all-zeros (an all-zero
+ * vector is honestly "no signal", never normalized).
+ */
+export function fakeEmbedOne(text, dims = FAKE_EMBEDDING_DIMS) {
+    const counts = new Array(dims).fill(0);
+    const tokens = text.toLowerCase().match(TOKEN_RE) ?? [];
+    for (const token of tokens) {
+        const bytes = sha256.array(token); // 32 bytes, 0..255
+        // big-endian uint32 of bytes[0..4) — `>>> 0` forces unsigned.
+        const idx = (((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0) % dims;
+        const sign = bytes[4] & 1 ? 1 : -1;
+        counts[idx] += sign;
+    }
+    let normSq = 0;
+    for (const c of counts)
+        normSq += c * c;
+    if (normSq === 0)
+        return counts; // already all-zeros
+    const norm = Math.sqrt(normSq);
+    return counts.map((c) => c / norm);
+}
+/**
+ * Zero-dependency `EmbeddingPort` — the offline/CI default. Structurally
+ * satisfies `EmbeddingPort` (`modelId`, `dims`, async `embed`).
+ */
+export class FakeEmbeddingProvider {
+    modelId = FAKE_EMBEDDING_MODEL_ID;
+    dims;
+    constructor(dims = FAKE_EMBEDDING_DIMS) {
+        this.dims = dims;
+    }
+    async embed(texts) {
+        return texts.map((t) => fakeEmbedOne(t, this.dims));
+    }
+}

package/dist/kernel/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Boot-time registration errors raised by Kernel.
+ *
+ * 1:1 parity with python/dna/kernel/errors.py.
+ *
+ * H1 — Boot-time validation. The Kernel's `kind/reader/writer/load`
+ * registration methods used to be `this._x.push(y)` no-ops with zero
+ * validation. Result: a typo in `detect()` made the Reader silently
+ * ignored; two bundle Readers using the same marker file collided
+ * (first-registered wins, depending on entry-point alphabetical order);
+ * duplicate `(apiVersion, kind)` registrations silently overwrote.
+ *
+ * These errors surface those problems at boot time instead of as silent
+ * runtime drift.
+ */
+/** Base class for kernel registration validation failures. */
+export declare class KernelRegistrationError extends Error {
+    constructor(message?: string);
+}
+/**
+ * A KindPort failed Protocol conformance, uniqueness, or marker
+ * collision checks at `kernel.kind(port)` time.
+ *
+ * Examples:
+ *   - Duplicate `(apiVersion, kind)` tuple
+ *   - Duplicate `alias` across registered Kinds
+ *   - Two BUNDLE-pattern Kinds declaring the same
+ *     `(storage.container, storage.marker)` pair
+ *   - Object passed doesn't satisfy the `KindPort` interface
+ */
+export declare class KindRegistrationError extends KernelRegistrationError {
+    constructor(message?: string);
+}
+/**
+ * A ReaderPort failed structural conformance or owner-binding checks
+ * at `kernel.reader(r)` time.
+ *
+ * Examples:
+ *   - Object missing `detect` or `read` methods
+ *   - Reader claims a `(container, marker)` pair already owned by
+ *     another reader
+ */
+export declare class ReaderRegistrationError extends KernelRegistrationError {
+    constructor(message?: string);
+}
+/**
+ * A WriterPort failed structural conformance checks at
+ * `kernel.writer(w)` time. Object missing `canWrite` or `write` is
+ * the typical case.
+ */
+export declare class WriterRegistrationError extends KernelRegistrationError {
+    constructor(message?: string);
+}
+/**
+ * An Extension failed structural checks at `kernel.load(ext)` time.
+ * Object missing `register` callable, or its `register` raised an
+ * unexpected exception that wasn't routed through the
+ * `extension_error` hook.
+ */
+export declare class ExtensionLoadError extends KernelRegistrationError {
+    constructor(message?: string);
+}

package/dist/kernel/errors.js

@@ -0,0 +1,82 @@
+/**
+ * Boot-time registration errors raised by Kernel.
+ *
+ * 1:1 parity with python/dna/kernel/errors.py.
+ *
+ * H1 — Boot-time validation. The Kernel's `kind/reader/writer/load`
+ * registration methods used to be `this._x.push(y)` no-ops with zero
+ * validation. Result: a typo in `detect()` made the Reader silently
+ * ignored; two bundle Readers using the same marker file collided
+ * (first-registered wins, depending on entry-point alphabetical order);
+ * duplicate `(apiVersion, kind)` registrations silently overwrote.
+ *
+ * These errors surface those problems at boot time instead of as silent
+ * runtime drift.
+ */
+/** Base class for kernel registration validation failures. */
+export class KernelRegistrationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KernelRegistrationError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * A KindPort failed Protocol conformance, uniqueness, or marker
+ * collision checks at `kernel.kind(port)` time.
+ *
+ * Examples:
+ *   - Duplicate `(apiVersion, kind)` tuple
+ *   - Duplicate `alias` across registered Kinds
+ *   - Two BUNDLE-pattern Kinds declaring the same
+ *     `(storage.container, storage.marker)` pair
+ *   - Object passed doesn't satisfy the `KindPort` interface
+ */
+export class KindRegistrationError extends KernelRegistrationError {
+    constructor(message) {
+        super(message);
+        this.name = "KindRegistrationError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * A ReaderPort failed structural conformance or owner-binding checks
+ * at `kernel.reader(r)` time.
+ *
+ * Examples:
+ *   - Object missing `detect` or `read` methods
+ *   - Reader claims a `(container, marker)` pair already owned by
+ *     another reader
+ */
+export class ReaderRegistrationError extends KernelRegistrationError {
+    constructor(message) {
+        super(message);
+        this.name = "ReaderRegistrationError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * A WriterPort failed structural conformance checks at
+ * `kernel.writer(w)` time. Object missing `canWrite` or `write` is
+ * the typical case.
+ */
+export class WriterRegistrationError extends KernelRegistrationError {
+    constructor(message) {
+        super(message);
+        this.name = "WriterRegistrationError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * An Extension failed structural checks at `kernel.load(ext)` time.
+ * Object missing `register` callable, or its `register` raised an
+ * unexpected exception that wasn't routed through the
+ * `extension_error` hook.
+ */
+export class ExtensionLoadError extends KernelRegistrationError {
+    constructor(message) {
+        super(message);
+        this.name = "ExtensionLoadError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/kernel/events.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Derive event types from Kind + update status for HookRegistry post_save.
+ * 1:1 parity with Python dna.kernel.events.
+ */
+export declare const DELETE_EVENT_TYPE = "document_deleted";
+export declare function deriveEventType(kind: string, isUpdate: boolean): string;

package/dist/kernel/events.js

@@ -0,0 +1,21 @@
+/**
+ * Derive event types from Kind + update status for HookRegistry post_save.
+ * 1:1 parity with Python dna.kernel.events.
+ */
+export const DELETE_EVENT_TYPE = "document_deleted";
+const FIXED_EVENTS = {
+    EvalRun: "eval_run_completed",
+    EvalBaseline: "baseline_pinned",
+};
+const SPLIT_EVENTS = {
+    Finding: ["finding_created", "finding_status_changed"],
+};
+export function deriveEventType(kind, isUpdate) {
+    const fixed = FIXED_EVENTS[kind];
+    if (fixed)
+        return fixed;
+    const split = SPLIT_EVENTS[kind];
+    if (split)
+        return isUpdate ? split[1] : split[0];
+    return isUpdate ? "document_modified" : "document_created";
+}

package/dist/kernel/evidence-capture.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Evidence capture handler — creates Evidence documents with SHA-256 hashes.
+ *
+ * ``computeContentHash`` produces a deterministic SHA-256 digest of
+ * canonical JSON (recursively sorted keys, no whitespace) so that key
+ * ordering never affects the hash.
+ *
+ * 1:1 parity with Python dna.extensions.evidence.builder.
+ */
+import type { HookContext } from "./hooks.js";
+/**
+ * Check whether *eventType* should be auto-captured per *policySpec*.
+ *
+ * Generic policy-evaluation logic (reads a plain EvidencePolicy spec dict),
+ * kernel-owned so the microkernel's capture handler needs no extension
+ * import (s-invert-evidence-capture-dep). EvidenceExtension re-exports this
+ * as its public API.
+ */
+export declare function shouldCapture(policySpec: Record<string, unknown>, eventType: string): boolean;
+/**
+ * SHA-256 of canonical JSON (async, browser-compatible).
+ *
+ * Uses Web Crypto API (available in Node 18+, Bun, and all browsers).
+ * Matches Python: ``json.dumps(sort_keys=True, separators=(",", ":"))``
+ */
+export declare function computeContentHash(content: unknown): Promise<string>;
+/**
+ * Derive the suite name from kind + spec, with explicit override.
+ *
+ * - EvalRun  -> spec.suite
+ * - Finding  -> spec.source
+ * - Explicit parameter always wins.
+ * - Non-eval kinds return null.
+ */
+export declare function extractSuite(kind: string, spec: Record<string, unknown>, explicit: string | null): string | null;
+export declare function buildEvidenceDoc(opts: {
+    eventType: string;
+    kind: string;
+    name: string;
+    spec: Record<string, unknown>;
+    author: string;
+    suite?: string | null;
+}): Promise<Record<string, unknown>>;
+/**
+ * The runtime capabilities the evidence-capture handler needs from the
+ * kernel it captures — a read surface (`instance()._all()`, the MI internal non-deprecated twin) plus the write
+ * path. Narrower than the full Kernel on purpose; the EvidenceExtension
+ * feature-tests these members before wiring the handler
+ * (s-dna-extension-host-contract).
+ */
+export interface EvidenceCaptureHost {
+    instance(scope: string): {
+        _all(kind: string): {
+            spec: Record<string, unknown>;
+        }[];
+    };
+    writeDocument(scope: string, kind: string, name: string, raw: Record<string, unknown>, options?: {
+        skipHooks?: boolean;
+        author?: string;
+    }): Promise<void>;
+}
+/**
+ * Create a ``post_save`` handler that auto-captures Evidence documents.
+ *
+ * The handler inspects EvidencePolicy documents in the current scope to
+ * decide whether to capture. Evidence documents themselves are skipped
+ * to avoid infinite loops, and the resulting write uses ``skipHooks: true``.
+ */
+export declare function makeEvidenceCaptureHandler(kernel: EvidenceCaptureHost): (ctx: HookContext) => void;

package/dist/kernel/evidence-capture.js

@@ -0,0 +1,138 @@
+/**
+ * Evidence capture handler — creates Evidence documents with SHA-256 hashes.
+ *
+ * ``computeContentHash`` produces a deterministic SHA-256 digest of
+ * canonical JSON (recursively sorted keys, no whitespace) so that key
+ * ordering never affects the hash.
+ *
+ * 1:1 parity with Python dna.extensions.evidence.builder.
+ */
+const EVAL_KINDS = new Set(["EvalRun", "EvalBaseline", "Finding"]);
+// ---------------------------------------------------------------------------
+// Policy evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Check whether *eventType* should be auto-captured per *policySpec*.
+ *
+ * Generic policy-evaluation logic (reads a plain EvidencePolicy spec dict),
+ * kernel-owned so the microkernel's capture handler needs no extension
+ * import (s-invert-evidence-capture-dep). EvidenceExtension re-exports this
+ * as its public API.
+ */
+export function shouldCapture(policySpec, eventType) {
+    if (policySpec.auto_capture === false)
+        return false;
+    const events = policySpec.events;
+    if (!Array.isArray(events))
+        return false;
+    return events.includes(eventType);
+}
+// ---------------------------------------------------------------------------
+// Canonical JSON helpers
+// ---------------------------------------------------------------------------
+/** Recursively sort object keys for canonical JSON (Python parity). */
+function sortDeep(val) {
+    if (val === null || val === undefined || typeof val !== "object")
+        return val;
+    if (Array.isArray(val))
+        return val.map(sortDeep);
+    const sorted = {};
+    for (const key of Object.keys(val).sort()) {
+        sorted[key] = sortDeep(val[key]);
+    }
+    return sorted;
+}
+/**
+ * SHA-256 of canonical JSON (async, browser-compatible).
+ *
+ * Uses Web Crypto API (available in Node 18+, Bun, and all browsers).
+ * Matches Python: ``json.dumps(sort_keys=True, separators=(",", ":"))``
+ */
+export async function computeContentHash(content) {
+    const canonical = JSON.stringify(sortDeep(content));
+    const data = new TextEncoder().encode(canonical);
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(hashBuffer))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+// ---------------------------------------------------------------------------
+// Suite extraction
+// ---------------------------------------------------------------------------
+/**
+ * Derive the suite name from kind + spec, with explicit override.
+ *
+ * - EvalRun  -> spec.suite
+ * - Finding  -> spec.source
+ * - Explicit parameter always wins.
+ * - Non-eval kinds return null.
+ */
+export function extractSuite(kind, spec, explicit) {
+    if (explicit)
+        return explicit;
+    if (!EVAL_KINDS.has(kind))
+        return null;
+    // The spec may be flat ({suite: "x"}) or nested ({spec: {suite: "x"}})
+    // depending on whether the caller passed the raw doc or just the spec field.
+    const inner = spec.spec ?? spec;
+    return inner.suite || inner.source || null;
+}
+// ---------------------------------------------------------------------------
+// Evidence document builder
+// ---------------------------------------------------------------------------
+export async function buildEvidenceDoc(opts) {
+    const now = new Date();
+    const suite = extractSuite(opts.kind, opts.spec, opts.suite ?? null);
+    const sha256 = await computeContentHash(opts.spec);
+    return {
+        apiVersion: "github.com/ruinosus/dna/evidence/v1",
+        kind: "Evidence",
+        metadata: { name: `ev-${opts.eventType}-${sha256.slice(0, 12)}` },
+        spec: {
+            event_type: opts.eventType,
+            sha256,
+            captured_at: now.toISOString(),
+            author: opts.author,
+            document_ref: `${opts.kind}:${opts.name}`,
+            suite,
+            snapshot: opts.spec,
+        },
+    };
+}
+/**
+ * Create a ``post_save`` handler that auto-captures Evidence documents.
+ *
+ * The handler inspects EvidencePolicy documents in the current scope to
+ * decide whether to capture. Evidence documents themselves are skipped
+ * to avoid infinite loops, and the resulting write uses ``skipHooks: true``.
+ */
+export function makeEvidenceCaptureHandler(kernel) {
+    return (ctx) => {
+        const { kind, name, data } = ctx;
+        const eventType = data.event_type || "";
+        // Never capture evidence about evidence (avoids infinite loop)
+        if (kind === "Evidence")
+            return;
+        const mi = kernel.instance(ctx.scope);
+        const policies = mi._all("EvidencePolicy");
+        if (!policies.some((p) => shouldCapture(p.spec, eventType)))
+            return;
+        // Async: build doc then write (fire-and-forget from hook perspective)
+        buildEvidenceDoc({
+            eventType,
+            kind: kind || "",
+            name: name || "",
+            spec: data.spec || {},
+            author: data.author || "unknown",
+            suite: data.suite,
+        })
+            .then((doc) => {
+            const evidenceName = doc.metadata.name;
+            return kernel.writeDocument(ctx.scope, "Evidence", evidenceName, doc, {
+                skipHooks: true,
+                author: "evidence-capture",
+            });
+        })
+            .catch((e) => console.warn(`Evidence capture failed for ${kind}:${name}:`, e));
+    };
+}

package/dist/kernel/fs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * FSLike — filesystem abstraction for readers/writers.
+ *
+ * Allows the SDK to run in Node.js (nodeFS), Tauri/webview (VFS adapter),
+ * or in-memory (createMemoryFS for tests).
+ */
+export interface FSLike {
+    exists(path: string): boolean;
+    readFile(path: string): string;
+    readDir(path: string): string[];
+    isDirectory(path: string): boolean;
+    isFile(path: string): boolean;
+    writeFile(path: string, content: string): void;
+    mkdir(path: string): void;
+}
+export declare const nodeFS: FSLike;
+export declare function createMemoryFS(initial?: Record<string, string>): FSLike;
+export declare function relativePath(root: string, full: string): string;
+export declare function readTextSafe(fs: FSLike, path: string): string | null;
+export declare function collectDir(fs: FSLike, directory: string, root: string): Record<string, string>;