dna-sdk 0.3.1 → 0.4.0

package/dist/adapters/source-url.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `sourceFromUrl` — the URL → SourcePort factory, as a PUBLIC SDK surface.
+ *
+ * 1:1 parity with python `dna/adapters/source_url.py`. Promotes URL→adapter
+ * resolution out of ad-hoc host code so `fromConfig()` and any host share ONE
+ * factory.
+ *
+ * Scheme map (TS runtime):
+ *
+ *   file:// <path>      → FilesystemSource (read/write on disk)
+ *   fs:// <path>        → alias of file://
+ *   <plain path>        → treated as file://<path>
+ *   postgresql:// …     → PostgresSource (node-postgres)
+ *   postgres:// …       → alias of postgresql://
+ *   sqlite:// <path>    → NOT SUPPORTED in the TS runtime (Python-only; the
+ *                         SqlAlchemy adapter is a Python thing) — fails loud.
+ *
+ * An unknown scheme fails loud with the supported set.
+ */
+import type { SourcePort } from "../kernel/protocols.js";
+export declare class UnsupportedSourceScheme extends Error {
+    constructor(message: string);
+}
+interface SourceFromUrlOptions {
+    /** Postgres schema namespace (postgres sources only). */
+    schema?: string;
+}
+/**
+ * Build a source from a scheme URL (see module docstring).
+ *
+ * Postgres sources run their migrations on first use; this awaits `init()` so
+ * the returned source is ready.
+ */
+export declare function sourceFromUrl(url: string, opts?: SourceFromUrlOptions): Promise<SourcePort>;
+/**
+ * The `file://` URL the SDK falls back to with no explicit config.
+ * Priority: explicit override > `DNA_BASE_DIR` env > `./.dna`.
+ */
+export declare function resolveDefaultFsUrl(baseDirOverride?: string): string;
+export {};

package/dist/adapters/source-url.js

@@ -0,0 +1,55 @@
+export class UnsupportedSourceScheme extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedSourceScheme";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+function urlToFsPath(url) {
+    // Mirror the Python rule (join netloc + path so `fs://./x` stays RELATIVE).
+    const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/(.*)$/.exec(url);
+    if (!m)
+        return url; // plain path, no scheme
+    return m[2]; // everything after scheme:// (host+path joined)
+}
+function schemeOf(url) {
+    const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url);
+    return (m ? m[1] : "file").toLowerCase();
+}
+/**
+ * Build a source from a scheme URL (see module docstring).
+ *
+ * Postgres sources run their migrations on first use; this awaits `init()` so
+ * the returned source is ready.
+ */
+export async function sourceFromUrl(url, opts = {}) {
+    const scheme = schemeOf(url);
+    const base = scheme.split("+", 1)[0];
+    if (scheme === "file" || scheme === "fs" || scheme === "") {
+        const { FilesystemSource } = await import("./filesystem/source.js");
+        return new FilesystemSource(urlToFsPath(url) || url);
+    }
+    if (base === "postgresql" || base === "postgres") {
+        const { PostgresSource } = await import("./postgres/source.js");
+        const src = new PostgresSource({ connectionString: url, schema: opts.schema });
+        await src.init();
+        return src;
+    }
+    if (base === "sqlite") {
+        throw new UnsupportedSourceScheme(`sqlite:// sources are Python-only — they ride the Python SqlAlchemy ` +
+            `adapter, which the TypeScript runtime does not ship. Use file:// ` +
+            `(filesystem) or postgresql:// here. Got: ${url}`);
+    }
+    throw new UnsupportedSourceScheme(`unsupported source URL scheme '${scheme}://' — the TS runtime ships ` +
+        `file:// (filesystem) and postgresql:// adapters. Got: ${url}`);
+}
+/**
+ * The `file://` URL the SDK falls back to with no explicit config.
+ * Priority: explicit override > `DNA_BASE_DIR` env > `./.dna`.
+ */
+export function resolveDefaultFsUrl(baseDirOverride) {
+    const base = baseDirOverride ?? process.env.DNA_BASE_DIR;
+    if (base)
+        return `file://${base}`;
+    return "file://.dna";
+}

package/dist/bootstrap.d.ts

@@ -43,3 +43,18 @@ export declare function createRuntimeWithBuiltins(): Runtime;
  * `ManifestInstance` for the given scope.
  */
 export declare function quickManifest(scope: string, baseDir?: string): Promise<ManifestInstance>;
+/**
+ * Boot a fully-wired Kernel from a `dna.config.yaml` (declarative port wiring —
+ * s-dx-kernel-from-config). TS twin of python `Kernel.from_config`.
+ *
+ * The config selects the `source` (`file://` / `postgresql://`) and,
+ * optionally, the `search` + `embedding` providers; every port is resolved to
+ * its adapter and wired. With NO config present (and no `path`) the behavior is
+ * unchanged — a filesystem `.dna` source, exactly like the bare default.
+ *
+ * Returns a wired Kernel; call `.instance(scope)` for the ManifestInstance.
+ * (Python exposes this as the `Kernel.from_config` static; the TS bootstrap
+ * keeps it a free function, mirroring `quickInstance` — same documented
+ * asymmetry the SDK already lives with.)
+ */
+export declare function fromConfig(path?: string): Promise<Kernel>;

package/dist/bootstrap.js

@@ -40,6 +40,8 @@ import { TestkitExtension } from "./extensions/testkit.js";
 import { ModelRegExtension } from "./extensions/modelreg.js";
 import { AutomationExtension } from "./extensions/automation.js";
 import { EvalExtension } from "./extensions/eval.js";
+import { loadConfig } from "./config.js";
+import { resolveDefaultFsUrl, sourceFromUrl } from "./adapters/source-url.js";
 /**
  * The canonical built-in extension set. Loaded into BOTH a Kernel and a
  * Runtime through this SINGLE list so the two bootstraps can never drift
@@ -132,3 +134,84 @@ export async function quickManifest(scope, baseDir = ".dna") {
     rt.resolver("github", new GitHubResolver());
     return rt.manifest(scope);
 }
+/** Minimal CachePort for non-filesystem sources (all docs self-contained).
+ *  TS twin of python `kernel_bootstrap._NoopCache`. */
+class NoopCache {
+    async loadAll() {
+        return [];
+    }
+    async loadKey() {
+        return [];
+    }
+    async store(_scope, _key, _items) {
+        // no-op
+    }
+    async has() {
+        return true; // pretend always hit → skip resolver calls
+    }
+}
+/**
+ * Boot a fully-wired Kernel from a `dna.config.yaml` (declarative port wiring —
+ * s-dx-kernel-from-config). TS twin of python `Kernel.from_config`.
+ *
+ * The config selects the `source` (`file://` / `postgresql://`) and,
+ * optionally, the `search` + `embedding` providers; every port is resolved to
+ * its adapter and wired. With NO config present (and no `path`) the behavior is
+ * unchanged — a filesystem `.dna` source, exactly like the bare default.
+ *
+ * Returns a wired Kernel; call `.instance(scope)` for the ManifestInstance.
+ * (Python exposes this as the `Kernel.from_config` static; the TS bootstrap
+ * keeps it a free function, mirroring `quickInstance` — same documented
+ * asymmetry the SDK already lives with.)
+ */
+export async function fromConfig(path) {
+    const cfg = loadConfig(path);
+    const sourceUrl = cfg ? cfg.source : resolveDefaultFsUrl();
+    const source = await sourceFromUrl(sourceUrl);
+    const k = createKernelWithBuiltins();
+    k.source(source);
+    if (source.supportsReaders) {
+        const baseDir = source.baseDir;
+        k.cache(new FilesystemCache(baseDir));
+        k.resolver("local", new LocalResolver(baseDir));
+        k.resolver("http", new HttpResolver());
+        k.resolver("https", new HttpResolver());
+        k.resolver("github", new GitHubResolver());
+    }
+    else {
+        k.cache(new NoopCache());
+    }
+    // Uniform writer/reader wiring for any KernelAttachable source.
+    const attach = source.attachKernel;
+    if (typeof attach === "function")
+        attach.call(source, k);
+    if (cfg) {
+        await wireSearch(k, cfg);
+        await wireEmbedding(k, cfg);
+    }
+    return k;
+}
+async function wireEmbedding(kernel, cfg) {
+    if (cfg.embedding === "off" || cfg.embedding === "fake")
+        return;
+    if (cfg.embedding === "onnx") {
+        // Dynamic import: the ONNX adapter (transformers.js) must never enter the
+        // default bundle (guard: tests/embedding-import-isolation.test.ts).
+        const { OnnxEmbeddingProvider } = await import("./adapters/embedding/onnx.js");
+        kernel.embeddingProvider(new OnnxEmbeddingProvider());
+    }
+}
+async function wireSearch(kernel, cfg) {
+    if (cfg.search === "off")
+        return;
+    if (cfg.search === "sqlite-vec") {
+        // Dynamic import: sqlite-vec must never enter the default bundle
+        // (guard: tests/search-import-isolation.test.ts).
+        const { SqliteVecRecordSearchProvider } = await import("./adapters/search/sqlite-vec.js");
+        kernel.recordSearchProvider(new SqliteVecRecordSearchProvider(kernel, {}));
+    }
+    else if (cfg.search === "pgvector") {
+        throw new Error("search: pgvector is Python-only in this build — the TS runtime ships " +
+            "the sqlite-vec record-search provider. Use `search: sqlite-vec` here.");
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+export declare const CONFIG_FILENAME = "dna.config.yaml";
+declare const VALID_SEARCH: readonly ["off", "pgvector", "sqlite-vec"];
+declare const VALID_EMBEDDING: readonly ["off", "fake", "onnx"];
+export type SearchMode = (typeof VALID_SEARCH)[number];
+export type EmbeddingMode = (typeof VALID_EMBEDDING)[number];
+/** Parsed + validated `dna.config.yaml`. */
+export interface DnaConfig {
+    /** Scheme URL: `file://` | `sqlite://` | `postgresql://`. */
+    source: string;
+    /** Record-search provider selector (default `off`). */
+    search: SearchMode;
+    /** Embedding provider selector (default `off`). */
+    embedding: EmbeddingMode;
+    /** Where it was loaded from (`null` for a synthesized default). */
+    path: string | null;
+}
+/**
+ * Path to `dna.config.yaml` in `start` (default: cwd), or `null` if absent.
+ * Deliberately NOT a walk-up — a config's meaning is tied to the boot dir.
+ */
+export declare function findConfig(start?: string): string | null;
+/**
+ * Load + validate `dna.config.yaml`.
+ *
+ * - `path` given → it MUST exist (a typo'd path is an error, not a silent
+ *   fallback); parsed and validated.
+ * - `path` omitted → look for `dna.config.yaml` in cwd. Found → parsed. Absent
+ *   → `null` (the caller keeps its default: a filesystem `.dna` source).
+ *
+ * Throws on: not-a-mapping, missing `source`, unknown keys, or an out-of-enum
+ * `search` / `embedding` value.
+ */
+export declare function loadConfig(path?: string): DnaConfig | null;
+export {};

package/dist/config.js

@@ -0,0 +1,102 @@
+/**
+ * `dna.config.yaml` — declarative port wiring (s-dx-kernel-from-config).
+ *
+ * 1:1 parity with python `dna/config.py`. The SAME file drives both SDKs — the
+ * schema is language-agnostic:
+ *
+ * ```yaml
+ * # dna.config.yaml
+ * source: postgresql://user:pass@host/db   # or sqlite:///./dev.db, file://.dna
+ * search: pgvector        # pgvector | sqlite-vec | off   (default: off)
+ * embedding: onnx         # onnx | fake | off             (default: off / fake floor)
+ * ```
+ *
+ * Only `source` is required. This module parses + VALIDATES the file (unknown
+ * keys and bad enum values fail loud); the wiring lives in `fromConfig()`.
+ *
+ * Runtime asymmetry (documented, not silent): the TS runtime ships the
+ * filesystem + postgres source adapters; `sqlite://` is Python-only (it rides
+ * the Python-only SqlAlchemy adapter). A `sqlite://` source — or a `pgvector`
+ * search — in a TS host fails loud with that explanation at wire time.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+export const CONFIG_FILENAME = "dna.config.yaml";
+const VALID_SEARCH = ["off", "pgvector", "sqlite-vec"];
+const VALID_EMBEDDING = ["off", "fake", "onnx"];
+const KNOWN_KEYS = new Set(["source", "search", "embedding"]);
+/**
+ * Path to `dna.config.yaml` in `start` (default: cwd), or `null` if absent.
+ * Deliberately NOT a walk-up — a config's meaning is tied to the boot dir.
+ */
+export function findConfig(start) {
+    const candidate = join(start ?? process.cwd(), CONFIG_FILENAME);
+    return existsSync(candidate) ? candidate : null;
+}
+/**
+ * Load + validate `dna.config.yaml`.
+ *
+ * - `path` given → it MUST exist (a typo'd path is an error, not a silent
+ *   fallback); parsed and validated.
+ * - `path` omitted → look for `dna.config.yaml` in cwd. Found → parsed. Absent
+ *   → `null` (the caller keeps its default: a filesystem `.dna` source).
+ *
+ * Throws on: not-a-mapping, missing `source`, unknown keys, or an out-of-enum
+ * `search` / `embedding` value.
+ */
+export function loadConfig(path) {
+    let resolved;
+    if (path !== undefined) {
+        if (!existsSync(path)) {
+            throw new Error(`dna config not found at ${path} — pass a path to an existing ` +
+                `${CONFIG_FILENAME}, or omit it to auto-discover one in the ` +
+                `current directory.`);
+        }
+        resolved = path;
+    }
+    else {
+        const found = findConfig();
+        if (found === null)
+            return null;
+        resolved = found;
+    }
+    const raw = yaml.load(readFileSync(resolved, "utf-8"));
+    return parse(raw, resolved);
+}
+function parse(raw, path) {
+    if (raw === null || raw === undefined) {
+        throw new Error(`${path} is empty — it must at least declare a \`source:\` URL ` +
+            `(e.g. \`source: file://.dna\`).`);
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`${path} must be a YAML mapping (key: value).`);
+    }
+    const obj = raw;
+    const unknown = Object.keys(obj).filter((k) => !KNOWN_KEYS.has(k)).sort();
+    if (unknown.length > 0) {
+        throw new Error(`${path}: unknown key(s) ${JSON.stringify(unknown)} — supported keys ` +
+            `are ${JSON.stringify([...KNOWN_KEYS].sort())}.`);
+    }
+    const source = obj.source;
+    if (typeof source !== "string" || source.length === 0) {
+        throw new Error(`${path}: \`source:\` is required and must be a URL string ` +
+            `(file:// | sqlite:// | postgresql://).`);
+    }
+    const search = String(obj.search ?? "off").trim() || "off";
+    if (!VALID_SEARCH.includes(search)) {
+        throw new Error(`${path}: \`search: ${search}\` is not valid — choose one of ` +
+            `${JSON.stringify(VALID_SEARCH)}.`);
+    }
+    const embedding = String(obj.embedding ?? "off").trim() || "off";
+    if (!VALID_EMBEDDING.includes(embedding)) {
+        throw new Error(`${path}: \`embedding: ${embedding}\` is not valid — choose one of ` +
+            `${JSON.stringify(VALID_EMBEDDING)}.`);
+    }
+    return {
+        source,
+        search: search,
+        embedding: embedding,
+        path,
+    };
+}

package/dist/index.d.ts

@@ -21,7 +21,12 @@ export { LockManager } from "./kernel/lock-manager.js";
 export { ReportBuilder } from "./kernel/reports.js";
 export { serializeRawToFiles } from "./kernel/serialize-to-files.js";
 export * from "./viz/index.js";
-export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest } from "./bootstrap.js";
+export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest, fromConfig } from "./bootstrap.js";
+export { AgentNotFound } from "./kernel/errors.js";
+export { PromptLibrary, loadPrompts } from "./prompts.js";
+export { loadConfig, findConfig, CONFIG_FILENAME } from "./config.js";
+export type { DnaConfig, SearchMode, EmbeddingMode } from "./config.js";
+export { sourceFromUrl, resolveDefaultFsUrl, UnsupportedSourceScheme } from "./adapters/source-url.js";
 export { HookRegistry, KNOWN_HOOK_NAMES } from "./kernel/hooks.js";
 export type { HookContext, HookName, HookNameArg, Middleware, EventHandler, PreSaveContext, VetoHandler, } from "./kernel/hooks.js";
 export type { SourcePort, CachePort, ResolverPort, ReaderPort, WriterPort, KindPort, KindPresentation, Extension, ExtensionHost, CompositionResult, CacheItem, ResolvedItem, StorageDescriptor, StoragePattern, BodyMode, SerializedFile, SerializedDocument, WritableSourcePort, QueryFilter, QueryOrder, CountResult, SourceQueryOpts, SourceCountOpts, RecordStorePort, RecordSearchProvider, EmbeddingPort, ToolPort, } from "./kernel/protocols.js";

package/dist/index.js

@@ -24,7 +24,13 @@ export { serializeRawToFiles } from "./kernel/serialize-to-files.js";
 // Viz — diagram generators, health, matrix, ASCII tree
 export * from "./viz/index.js";
 // Opinionated bootstrap — extension wiring lives here, not in kernel/
-export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest } from "./bootstrap.js";
+export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest, fromConfig } from "./bootstrap.js";
+// DX consumer surface (s-dx-*): fail-loud prompt building + the collapse-the-
+// shim helper + declarative port wiring.
+export { AgentNotFound } from "./kernel/errors.js";
+export { PromptLibrary, loadPrompts } from "./prompts.js";
+export { loadConfig, findConfig, CONFIG_FILENAME } from "./config.js";
+export { sourceFromUrl, resolveDefaultFsUrl, UnsupportedSourceScheme } from "./adapters/source-url.js";
 export { HookRegistry, KNOWN_HOOK_NAMES } from "./kernel/hooks.js";
 // i-005 — types REFERENCED by already-exported public API, previously
 // broken xrefs in TypeDoc. Each is public surface a consumer needs to name:

package/dist/kernel/errors.d.ts

@@ -13,6 +13,24 @@
  * These errors surface those problems at boot time instead of as silent
  * runtime drift.
  */
+/**
+ * `buildPrompt({ agent: X })` was asked for an agent that no prompt-target
+ * document in the loaded manifest declares (missing, renamed, or unparseable).
+ *
+ * Fail-loud contract (s-dx-build-prompt-fail-loud): the builder used to RETURN
+ * the string `"Agent 'X' not found"` instead of throwing — which sailed
+ * straight through a consumer's `if (!text)` check and became the LITERAL
+ * agent instruction. Every consumer therefore wrote the same defensive guard
+ * (`mi.findAgent(x) === null`) before every call. Throwing a typed error
+ * deletes that guard: the miss is now impossible to ignore.
+ *
+ * 1:1 parity with python `dna.AgentNotFound` (a `LookupError` subclass).
+ * Exported publicly from the package root.
+ */
+export declare class AgentNotFound extends Error {
+    readonly agent: string | null;
+    constructor(agent: string | null);
+}
 /** Base class for kernel registration validation failures. */
 export declare class KernelRegistrationError extends Error {
     constructor(message?: string);

package/dist/kernel/errors.js

@@ -13,6 +13,29 @@
  * These errors surface those problems at boot time instead of as silent
  * runtime drift.
  */
+/**
+ * `buildPrompt({ agent: X })` was asked for an agent that no prompt-target
+ * document in the loaded manifest declares (missing, renamed, or unparseable).
+ *
+ * Fail-loud contract (s-dx-build-prompt-fail-loud): the builder used to RETURN
+ * the string `"Agent 'X' not found"` instead of throwing — which sailed
+ * straight through a consumer's `if (!text)` check and became the LITERAL
+ * agent instruction. Every consumer therefore wrote the same defensive guard
+ * (`mi.findAgent(x) === null`) before every call. Throwing a typed error
+ * deletes that guard: the miss is now impossible to ignore.
+ *
+ * 1:1 parity with python `dna.AgentNotFound` (a `LookupError` subclass).
+ * Exported publicly from the package root.
+ */
+export class AgentNotFound extends Error {
+    agent;
+    constructor(agent) {
+        super(`Agent '${agent}' not found`);
+        this.name = "AgentNotFound";
+        this.agent = agent;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 /** Base class for kernel registration validation failures. */
 export class KernelRegistrationError extends Error {
     constructor(message) {

package/dist/kernel/prompt-builder.js

@@ -10,6 +10,7 @@
  */
 import Mustache from "mustache";
 import { stripPromptBlock } from "./_text.js";
+import { AgentNotFound } from "./errors.js";
 // ---------------------------------------------------------------------------
 // PromptBuilder
 // ---------------------------------------------------------------------------
@@ -38,7 +39,10 @@ export class PromptBuilder {
         }
         const agentDoc = agentName ? this._findAgent(agentName) : null;
         if (!agentDoc) {
-            return `Agent '${agentName}' not found`;
+            // Fail loud (s-dx-build-prompt-fail-loud): throw a typed error instead
+            // of returning a placeholder string that would become the literal
+            // instruction.
+            throw new AgentNotFound(agentName);
         }
         // Build context — merge backwards-compat params into enabledSlots
         const enabledSlots = { ...(opts?.enabledSlots ?? {}) };
@@ -69,7 +73,10 @@ export class PromptBuilder {
                 data: {},
             });
         }
-        return prompt;
+        // Clean output (s-dx-clean-composition-output): template sections can pad
+        // the composed prompt with trailing newlines; consumers used to strip them
+        // themselves. Return it already clean.
+        return prompt.replace(/\n+$/, "");
     }
     // -------------------------------------------------------------------------
     // Private helpers

package/dist/prompts.d.ts

@@ -0,0 +1,27 @@
+import type { ManifestInstance } from "./kernel/instance.js";
+/** Lazy, cached view `agent name -> composed prompt` over one scope. */
+export declare class PromptLibrary {
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    readonly mi: ManifestInstance;
+    private readonly cache;
+    constructor(
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    mi: ManifestInstance);
+    /**
+     * Compose `name`'s prompt (cached). Throws {@link AgentNotFound} on a miss;
+     * the returned text is clean (no trailing newlines).
+     */
+    get(name: string): Promise<string>;
+    /** True when `name` is a prompt-target document in the scope (no compose). */
+    has(name: string): boolean;
+    /** Names of every prompt-target document in the scope, sorted. */
+    names(): string[];
+}
+/**
+ * Compose the prompts of `scope` behind a {@link PromptLibrary}.
+ *
+ * `baseDir` follows the {@link quickInstance} convention — the directory that
+ * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
+ * var, then `.dna` in the cwd.
+ */
+export declare function loadPrompts(scope: string, baseDir?: string): Promise<PromptLibrary>;

package/dist/prompts.js

@@ -0,0 +1,76 @@
+/**
+ * `loadPrompts` — the one call that collapses the prompt shim (TS twin of
+ * python `dna.load_prompts`).
+ *
+ * With the fail-loud builder (s-dx-build-prompt-fail-loud) and clean output
+ * (s-dx-clean-composition-output) in place, a hand-rolled prompt module
+ * becomes:
+ *
+ * ```ts
+ * import { loadPrompts } from "@ruinosus/dna";
+ *
+ * const prompts = await loadPrompts("helpdesk");
+ * export const TRIAGE = await prompts.get("triage"); // composed, clean, or throws
+ * ```
+ *
+ * `loadPrompts` boots a filesystem kernel for `scope` and returns a
+ * {@link PromptLibrary} — a lazy, cached, read-only view from agent name to
+ * composed system prompt. A missing agent throws {@link AgentNotFound} (never a
+ * placeholder string); the returned text is already stripped of trailing
+ * newlines.
+ *
+ * TS/Py asymmetry: composition is async in TS, so `get(name)` returns a
+ * `Promise<string>` (python's `lib[name]` is sync — same reason `buildPrompt`
+ * is `await`ed in TS but not in Python).
+ */
+import { quickInstance } from "./bootstrap.js";
+/** Lazy, cached view `agent name -> composed prompt` over one scope. */
+export class PromptLibrary {
+    mi;
+    cache = new Map();
+    constructor(
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    mi) {
+        this.mi = mi;
+    }
+    /**
+     * Compose `name`'s prompt (cached). Throws {@link AgentNotFound} on a miss;
+     * the returned text is clean (no trailing newlines).
+     */
+    async get(name) {
+        const cached = this.cache.get(name);
+        if (cached !== undefined)
+            return cached;
+        // buildPrompt throws AgentNotFound on a miss and returns clean text.
+        const text = await this.mi.buildPrompt({ agent: name });
+        this.cache.set(name, text);
+        return text;
+    }
+    /** True when `name` is a prompt-target document in the scope (no compose). */
+    has(name) {
+        return this.names().includes(name);
+    }
+    /** Names of every prompt-target document in the scope, sorted. */
+    names() {
+        const kinds = this.mi._kinds;
+        const seen = new Set();
+        for (const doc of this.mi.documents) {
+            const kp = kinds.get(`${doc.apiVersion}\0${doc.kind}`);
+            if (kp?.isPromptTarget)
+                seen.add(doc.name);
+        }
+        return [...seen].sort();
+    }
+}
+/**
+ * Compose the prompts of `scope` behind a {@link PromptLibrary}.
+ *
+ * `baseDir` follows the {@link quickInstance} convention — the directory that
+ * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
+ * var, then `.dna` in the cwd.
+ */
+export async function loadPrompts(scope, baseDir) {
+    const resolved = baseDir ?? process.env.DNA_BASE_DIR ?? ".dna";
+    const mi = await quickInstance(scope, resolved);
+    return new PromptLibrary(mi);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dna-sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "DNA — Domain Notation of Anything (TypeScript SDK)",
   "type": "module",
   "license": "MIT",