dna-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DNA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# dna-sdk (TypeScript)
+
+TypeScript SDK for **DNA — Domain Notation of Anything**: a microkernel +
+extensions runtime for declarative agent notation. 1:1 behavioral twin of
+the Python SDK (`packages/sdk-py`) — same ports, same composition rules,
+same outputs, parity-enforced by tests. See the
+[repository README](https://github.com/ruinosus/dna#readme) for the thesis and the Kind catalog.
+
+## Install
+
+```bash
+npm install dna-sdk        # or: bun add dna-sdk
+```
+
+Pre-release / exact-pin alternative — consume straight from the repo:
+
+```bash
+cd packages/sdk-ts
+bun install
+```
+
+ESM-only, Node >= 20 or Bun. The published package ships compiled JS +
+type declarations (`dist/`); inside the repo, dev and tests run the
+TypeScript sources directly under Bun (no build step needed). The
+publication build is `bun run build` (tsc emit + runtime-asset copy).
+
+## Minimal example
+
+```typescript
+import { quickInstance } from "dna-sdk";
+
+// Scan a scope (directory of YAML/Markdown manifests under .dna/)
+const mi = await quickInstance("hello-genome", "examples/hello-genome/.dna");
+
+// Every document is identified by (apiVersion, kind, name)
+for (const d of mi.documents) {
+  console.log(d.apiVersion, d.kind, d.name);
+}
+
+// Compose agent + soul + skills + guardrails into one system prompt
+console.log(await mi.buildPrompt({ agent: "greeter" }));
+```
+
+Runnable version: [`examples/hello-genome/run.ts`](https://github.com/ruinosus/dna/blob/main/examples/hello-genome/run.ts).
+
+Prefer `createKernelWithBuiltins()` (from the same entrypoint) when you
+want to wire sources, caches and resolvers yourself.
+
+## Tests
+
+```bash
+bun test              # full suite
+bun run typecheck     # tsc --noEmit
+```
+
+The suite includes the market-fidelity conformance tests
+(`tests/market-conformance.test.ts`) and the Py↔TS parity fixtures shared
+with the Python twin.

package/dist/adapters/embedding/onnx.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ONNX all-MiniLM-L6-v2 embedding provider (optional `@huggingface/transformers`
+ * peer dep).
+ *
+ * The REAL embedder (rec-embedding-port): the same
+ * `sentence-transformers/all-MiniLM-L6-v2` ONNX artifact run by
+ * `@huggingface/transformers` (transformers.js, TS) and `fastembed` (Py) —
+ * parity by artifact, not reimplementation. Cosine ≈ 1 across the two runtimes.
+ *
+ * Lazy-download + cache, the Chroma pattern: the model is a downloaded artifact,
+ * never a bundled dependency. `@huggingface/transformers` is dynamically
+ * imported on the FIRST `embed` call and the pipeline fetches + caches the ONNX
+ * then — so this module never pulls transformers.js into a process that does
+ * not embed, and it is not in the default dependency graph.
+ */
+import type { EmbeddingPort } from "../../kernel/protocols.js";
+export declare const ONNX_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+export declare const ONNX_DIMS = 384;
+/**
+ * `EmbeddingPort` backed by transformers.js feature-extraction. The heavy
+ * dynamic import (`@huggingface/transformers`) is deferred to first use so
+ * merely importing this module never pulls ML deps into a process that does not
+ * embed.
+ */
+export declare class OnnxEmbeddingProvider implements EmbeddingPort {
+    readonly modelId: string;
+    readonly dims: number;
+    private _pipe;
+    constructor(modelId?: string, dims?: number);
+    private ensurePipe;
+    embed(texts: string[]): Promise<number[][]>;
+}

package/dist/adapters/embedding/onnx.js

@@ -0,0 +1,51 @@
+// Same model + vector width as the Py twin (adapters/embedding/onnx.py) and the
+// fake floor (FAKE_EMBEDDING_DIMS) so providers are swap-compatible.
+export const ONNX_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+export const ONNX_DIMS = 384;
+/**
+ * `EmbeddingPort` backed by transformers.js feature-extraction. The heavy
+ * dynamic import (`@huggingface/transformers`) is deferred to first use so
+ * merely importing this module never pulls ML deps into a process that does not
+ * embed.
+ */
+export class OnnxEmbeddingProvider {
+    modelId;
+    dims;
+    // The transformers.js pipeline, lazily constructed on first embed().
+    _pipe = null;
+    constructor(modelId = ONNX_MODEL_ID, dims = ONNX_DIMS) {
+        this.modelId = modelId;
+        this.dims = dims;
+    }
+    async ensurePipe() {
+        if (this._pipe === null) {
+            let mod;
+            // NON-LITERAL specifier on purpose: the peer dep is OPTIONAL and its
+            // type declarations are NOT installed by default, so a literal
+            // `import("@huggingface/transformers")` would fail `tsc --noEmit` in CI
+            // with TS2307. A string variable makes the dynamic import resolve to
+            // `Promise<any>` at type-check time (still the same module at runtime).
+            const spec = "@huggingface/transformers";
+            try {
+                // Dynamic import so the dep is optional and never bundled by default.
+                mod = (await import(/* @vite-ignore */ spec));
+            }
+            catch (err) {
+                throw new Error("OnnxEmbeddingProvider needs the '@huggingface/transformers' peer dep: "
+                    + "npm install @huggingface/transformers", { cause: err });
+            }
+            // Downloads + caches the ONNX artifact on first construction.
+            this._pipe = await mod.pipeline("feature-extraction", this.modelId);
+        }
+        return this._pipe;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const pipe = await this.ensurePipe();
+        // Mean-pooled + L2-normalized sentence vectors — same recipe fastembed
+        // uses by default, matching sentence-transformers.
+        const out = await pipe(texts, { pooling: "mean", normalize: true });
+        return out.tolist();
+    }
+}

package/dist/adapters/filesystem/cache.d.ts

@@ -0,0 +1,16 @@
+/**
+ * FilesystemCache — CachePort backed by .dna-cache/ directories.
+ *
+ * 1:1 parity with Python dna.v3.adapters.filesystem.cache.
+ */
+import type { CacheItem, CachePort, ReaderPort } from "../../kernel/protocols.js";
+export declare class FilesystemCache implements CachePort {
+    readonly baseDir: string;
+    private readonly _cacheDir;
+    constructor(baseDir: string);
+    has(scope: string, key: string): Promise<boolean>;
+    store(scope: string, key: string, items: CacheItem[]): Promise<void>;
+    loadKey(scope: string, key: string, readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+    loadAll(scope: string, readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+    private _readTree;
+}

package/dist/adapters/filesystem/cache.js

@@ -0,0 +1,113 @@
+/**
+ * FilesystemCache — CachePort backed by .dna-cache/ directories.
+ *
+ * 1:1 parity with Python dna.v3.adapters.filesystem.cache.
+ */
+import { access, cp, mkdir, readFile, readdir, rm, stat } from "node:fs/promises";
+import { resolve, join, dirname } from "node:path";
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+import yaml from "js-yaml";
+import { FilesystemBundleHandle } from "../../kernel/bundle-handle.js";
+export class FilesystemCache {
+    baseDir;
+    _cacheDir;
+    constructor(baseDir) {
+        this.baseDir = resolve(baseDir);
+        this._cacheDir = join(dirname(this.baseDir), ".dna-cache");
+    }
+    async has(scope, key) {
+        return pathExists(join(this._cacheDir, scope, key));
+    }
+    async store(scope, key, items) {
+        const destBase = join(this._cacheDir, scope, key);
+        await mkdir(destBase, { recursive: true });
+        for (const item of items) {
+            const subDir = item.kind
+                ? join(destBase, item.kind.toLowerCase() + "s")
+                : destBase;
+            const dest = join(subDir, item.name);
+            if (await pathExists(dest)) {
+                await rm(dest, { recursive: true, force: true });
+            }
+            await mkdir(dirname(dest), { recursive: true });
+            await cp(item.contentPath, dest, { recursive: true });
+        }
+    }
+    async loadKey(scope, key, readers) {
+        const keyDir = join(this._cacheDir, scope, key);
+        if (!(await pathExists(keyDir)))
+            return [];
+        const documents = [];
+        await this._readTree(keyDir, readers ?? [], documents);
+        return documents;
+    }
+    async loadAll(scope, readers) {
+        const scopeDir = join(this._cacheDir, scope);
+        if (!(await pathExists(scopeDir)))
+            return [];
+        const documents = [];
+        await this._readTree(scopeDir, readers ?? [], documents);
+        return documents;
+    }
+    async _readTree(directory, readers, documents) {
+        const entries = (await readdir(directory)).sort();
+        for (const entry of entries) {
+            const full = join(directory, entry);
+            if (!(await stat(full)).isDirectory())
+                continue;
+            let matched = false;
+            const handle = new FilesystemBundleHandle(full);
+            for (const reader of readers) {
+                try {
+                    if (await reader.detect(handle)) {
+                        const doc = await reader.read(handle);
+                        if (doc != null &&
+                            typeof doc === "object" &&
+                            "kind" in doc) {
+                            documents.push(doc);
+                        }
+                        matched = true;
+                        break;
+                    }
+                }
+                catch {
+                    // Skip reader errors
+                }
+            }
+            if (matched)
+                continue;
+            let hasYaml = false;
+            const subEntries = (await readdir(full)).sort();
+            for (const sub of subEntries) {
+                if (!sub.endsWith(".yaml") && !sub.endsWith(".yml"))
+                    continue;
+                const yf = join(full, sub);
+                if (!(await stat(yf)).isFile())
+                    continue;
+                try {
+                    const content = yaml.load(await readFile(yf, "utf-8"));
+                    if (content != null &&
+                        typeof content === "object" &&
+                        "kind" in content) {
+                        documents.push(content);
+                        hasYaml = true;
+                    }
+                }
+                catch {
+                    // Skip unparseable YAML
+                }
+            }
+            if (!hasYaml) {
+                await this._readTree(full, readers, documents);
+            }
+        }
+    }
+}

package/dist/adapters/filesystem/index.d.ts

@@ -0,0 +1,2 @@
+export { FilesystemSource } from "./source.js";
+export { FilesystemCache } from "./cache.js";

package/dist/adapters/filesystem/index.js

@@ -0,0 +1,2 @@
+export { FilesystemSource } from "./source.js";
+export { FilesystemCache } from "./cache.js";

package/dist/adapters/filesystem/source.d.ts

@@ -0,0 +1,82 @@
+/**
+ * FilesystemSource — SourcePort backed by local .dna/ directories.
+ *
+ * 1:1 parity with Python dna.v3.adapters.filesystem.source.
+ */
+import type { CountResult, ReaderPort, SourceCountOpts, SourcePort, SourceQueryOpts } from "../../kernel/protocols.js";
+import type { SourceCapabilities } from "../../kernel/capabilities.js";
+export declare class FilesystemSource implements SourcePort {
+    readonly baseDir: string;
+    readonly supportsReaders = true;
+    constructor(baseDir: string);
+    loadBootstrapDocs(scope: string, opts?: {
+        tenant?: string;
+    }): Promise<Record<string, unknown>[]>;
+    loadAll(scope: string, readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+    /**
+     * Two-planes F2 — record-plane query over `loadAll` + the shared pure
+     * helpers (mirror of the Py `SourcePort.query` protocol-default). FS
+     * is dev-mode with small scopes; native push-down is the purview of
+     * the SQL adapters.
+     *
+     * `opts.tenant` is a documented NO-OP here: the FS TS adapter has no
+     * tenant-aware overlay merge in `loadAll` (divergence from the Py FS
+     * source, which unions base + tenant layer with shadowing) — overlay
+     * support is an F2.5 candidate alongside the writable FS source.
+     *
+     * Bundle-format kinds are not visible to this query (no kernel reader
+     * back-ref on the TS source) — record-plane docs are plain YAML.
+     */
+    query(scope: string, kind: string, opts?: SourceQueryOpts): AsyncIterable<Record<string, unknown>>;
+    /**
+     * Two-planes F2 — record-plane count over `loadAll` + `countDocs`
+     * (mirror of the Py protocol-default). Same `opts.tenant` NO-OP
+     * caveat as `query`.
+     */
+    count(scope: string, kind: string, opts?: SourceCountOpts): Promise<CountResult>;
+    /**
+     * Explicit contract declaration (s-sourceport-contract-cleanup) — kept
+     * honest by the adapter conformance test (declaration == structural
+     * derivation). Read-only FS source: in-memory query/count + the L1
+     * granular reads (loadOne + listDocRefs, s-dna-port-surface-parity);
+     * no bundle/write surface on the TS twin yet.
+     */
+    capabilities(): SourceCapabilities;
+    /**
+     * Documented NO-OP — the FS source holds no pooled resources (each read
+     * opens/closes its own file handles via fs/promises). The member exists
+     * for SourcePort surface parity with Python, where `close` is a
+     * SOURCE_PORT_CORE_MEMBERS boot-gate entry.
+     */
+    close(): Promise<void>;
+    /**
+     * L1 granular access — FS impl projects from `loadAll` (mirror of the
+     * Py `FilesystemSource.list_doc_refs`): `[kind, name]` refs only, no
+     * bundle rehydration. No perf gain over `loadAll` on FS, but keeps the
+     * SourcePort contract consistent across adapters (PG is where the gain
+     * lives). Tenant: union of base + overlay with the overlay shadowing
+     * base, same as the Py twin. Result sorted by (kind, name).
+     */
+    listDocRefs(scope: string, opts?: {
+        kind?: string | null;
+        tenant?: string | null;
+    }): Promise<Array<[string, string]>>;
+    resolveRef(scope: string, ref: string): Promise<string>;
+    /**
+     * L1 granular access — FS impl projects from `loadAll` (mirror of the
+     * Py `FilesystemSource.load_one`). No perf gain over `loadAll` on FS
+     * (cheap in-process disk reads) but keeps the SourcePort contract
+     * consistent across adapters. Tenant overlay shadows base: when
+     * `opts.tenant` is set the tenant layer is consulted first and the
+     * BASE layer is the fallback (same as Python — a tenant read of a doc
+     * with no overlay still returns the base doc).
+     */
+    loadOne(scope: string, kind: string, name: string, opts?: {
+        readers?: ReaderPort[];
+        tenant?: string | null;
+    }): Promise<Record<string, unknown> | null>;
+    loadLayer(scope: string, layerId: string, layerValue: string, readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+    private _loadDir;
+    private _collectYaml;
+    private _readRecursive;
+}