dna-sdk 0.1.0

package/dist/kernel/navigator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Navigator — namespace class extracting navigation/display logic
+ * from ManifestInstance.
+ *
+ * Usage: `mi.nav.describe(...)`, `mi.nav.summary()`, `mi.nav.inventory()`, etc.
+ *
+ * This is an extraction (Chunk 2 of the kernel simplification plan).
+ * The original methods on ManifestInstance are preserved as one-line
+ * delegates; the canonical logic lives here.
+ */
+import { type PreviewBlock } from "./preview.js";
+import type { ManifestInstance } from "./instance.js";
+export declare class Navigator {
+    private host;
+    constructor(host: ManifestInstance);
+    /**
+     * Describe a single document.
+     * Equivalent to `mi.describe(kind, name)`.
+     */
+    describe(kind: string, name: string): string;
+    /**
+     * Produce a text summary of the manifest.
+     * Equivalent to `mi.summary()`.
+     */
+    summary(): string;
+    /**
+     * Produce a structured inventory of the manifest.
+     * Equivalent to `mi.inventory()`.
+     */
+    inventory(): Record<string, unknown>;
+    /**
+     * Polymorphic per-kind preview.
+     * Equivalent to `mi.renderDoc(kind, name)`.
+     */
+    renderDoc(kind: string, name: string): PreviewBlock[];
+}

package/dist/kernel/navigator.js

@@ -0,0 +1,132 @@
+/**
+ * Navigator — namespace class extracting navigation/display logic
+ * from ManifestInstance.
+ *
+ * Usage: `mi.nav.describe(...)`, `mi.nav.summary()`, `mi.nav.inventory()`, etc.
+ *
+ * This is an extraction (Chunk 2 of the kernel simplification plan).
+ * The original methods on ManifestInstance are preserved as one-line
+ * delegates; the canonical logic lives here.
+ */
+import { genericSpecDump } from "./preview.js";
+// ---------------------------------------------------------------------------
+// Navigator
+// ---------------------------------------------------------------------------
+export class Navigator {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * Describe a single document.
+     * Equivalent to `mi.describe(kind, name)`.
+     */
+    describe(kind, name) {
+        const doc = this.host._one(kind, name);
+        if (!doc)
+            return `${kind}/${name} not found`;
+        const kinds = this.host._kinds;
+        const kp = kinds.get(`${doc.apiVersion}\0${doc.kind}`);
+        if (kp) {
+            const custom = kp.describe(doc);
+            if (custom)
+                return custom;
+        }
+        const lines = [
+            `Name:       ${doc.name}`,
+            `Kind:       ${doc.kind}`,
+            `ApiVersion: ${doc.apiVersion}`,
+        ];
+        const desc = doc.metadata.description;
+        if (desc) {
+            lines.push(`Description: ${desc}`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Produce a text summary of the manifest.
+     * Equivalent to `mi.summary()`.
+     */
+    summary() {
+        const kinds = this.host.listKinds();
+        const lines = [`Scope: ${this.host.scope}`, `Kinds: ${kinds.length}`];
+        for (const k of kinds) {
+            const docs = this.host._all(k);
+            lines.push(`  ${k}: ${docs.length} (${docs.map((d) => d.name).join(", ")})`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Produce a structured inventory of the manifest.
+     * Equivalent to `mi.inventory()`.
+     */
+    inventory() {
+        const kinds = this.host._kinds;
+        const kindsData = {};
+        for (const kindName of this.host.listKinds()) {
+            const docs = this.host._all(kindName);
+            const docEntries = [];
+            for (const doc of docs) {
+                const entry = {
+                    name: doc.name,
+                    description: doc.metadata.description ?? "",
+                };
+                const key = `${doc.apiVersion}\0${doc.kind}`;
+                const kp = kinds.get(key);
+                if (kp) {
+                    const filters = kp.depFilters();
+                    if (filters) {
+                        const refs = {};
+                        const spec = doc.spec;
+                        for (const [specField] of Object.entries(filters)) {
+                            const val = spec[specField];
+                            if (val != null) {
+                                refs[specField] = val;
+                            }
+                        }
+                        if (Object.keys(refs).length > 0) {
+                            entry.refs = refs;
+                        }
+                    }
+                    const extra = kp.summary(doc);
+                    if (extra) {
+                        Object.assign(entry, extra);
+                    }
+                }
+                docEntries.push(entry);
+            }
+            kindsData[kindName] = {
+                count: docs.length,
+                documents: docEntries,
+            };
+        }
+        const comp = this.host.compositionResult;
+        return {
+            scope: this.host.scope,
+            total_documents: this.host.documents.length,
+            kinds: kindsData,
+            composition: {
+                valid: comp.missing.length === 0,
+                resolved: comp.resolved,
+                missing: comp.missing,
+                warnings: comp.warnings,
+                deferred: comp.deferred,
+            },
+        };
+    }
+    /**
+     * Polymorphic per-kind preview.
+     * Equivalent to `mi.renderDoc(kind, name)`.
+     */
+    renderDoc(kind, name) {
+        const doc = this.host._one(kind, name);
+        if (!doc)
+            return [];
+        const kinds = this.host._kinds;
+        const kp = kinds.get(`${doc.apiVersion}\0${doc.kind}`);
+        if (kp && typeof kp.preview === "function") {
+            return kp.preview(doc);
+        }
+        return genericSpecDump(doc);
+    }
+}

package/dist/kernel/port-surface.d.ts

@@ -0,0 +1,33 @@
+/**
+ * PORT_SURFACE — static member manifest of the public port interfaces
+ * (s-dna-port-surface-parity).
+ *
+ * TS interfaces are erased at runtime, so the port-surface parity test
+ * can't introspect them the way the Python twin introspects its
+ * `typing.Protocol`s. Instead, this module declares each port's member
+ * list as a const — and BINDS it to the real interface at compile time:
+ *
+ *   - every listed member must be a `keyof` the interface (no phantom
+ *     members), and
+ *   - the list must be EXHAUSTIVE (a member added to the interface but
+ *     not listed here fails `tsc --noEmit` with the missing name in the
+ *     error type).
+ *
+ * `tests/port-surface-parity.test.ts` then compares this manifest against
+ * the shared fixture `tests/parity-fixtures/port-surface-parity.json`
+ * (which the Py suite checks against the real Protocols) — so the two
+ * SDKs' port surfaces can only drift through an explicit, justified
+ * fixture edit.
+ */
+import type { BundleEntryReadable, KernelAttachable, Versionable } from "./capabilities.js";
+/**
+ * Compile-time existence proof for the capability interfaces tracked as
+ * NAMES (not keys) in the fixture's `CapabilityProtocols` pseudo-port —
+ * deleting/renaming one breaks this alias.
+ */
+export type CapabilityProtocolsProof = [
+    BundleEntryReadable,
+    KernelAttachable,
+    Versionable
+];
+export declare const PORT_SURFACE: Readonly<Record<string, readonly string[]>>;

package/dist/kernel/port-surface.js

@@ -0,0 +1,180 @@
+/**
+ * PORT_SURFACE — static member manifest of the public port interfaces
+ * (s-dna-port-surface-parity).
+ *
+ * TS interfaces are erased at runtime, so the port-surface parity test
+ * can't introspect them the way the Python twin introspects its
+ * `typing.Protocol`s. Instead, this module declares each port's member
+ * list as a const — and BINDS it to the real interface at compile time:
+ *
+ *   - every listed member must be a `keyof` the interface (no phantom
+ *     members), and
+ *   - the list must be EXHAUSTIVE (a member added to the interface but
+ *     not listed here fails `tsc --noEmit` with the missing name in the
+ *     error type).
+ *
+ * `tests/port-surface-parity.test.ts` then compares this manifest against
+ * the shared fixture `tests/parity-fixtures/port-surface-parity.json`
+ * (which the Py suite checks against the real Protocols) — so the two
+ * SDKs' port surfaces can only drift through an explicit, justified
+ * fixture edit.
+ */
+/**
+ * Compile-time exhaustive-keys binder. `keysOf<T>()([...])` only accepts
+ * an array whose entries are ALL keys of `T` and which covers EVERY key
+ * of `T` — otherwise the intersection with the `__missing_members__`
+ * brand fails to typecheck, naming the missing key(s) in the error.
+ */
+function keysOf() {
+    return (keys) => keys;
+}
+export const PORT_SURFACE = {
+    SourcePort: keysOf()([
+        "supportsReaders",
+        "loadBootstrapDocs",
+        "loadAll",
+        "resolveRef",
+        "loadLayer",
+        "close",
+        "listDocRefs",
+        "loadOne",
+        "query",
+        "count",
+        "capabilities",
+    ]),
+    // OWN members only — the inherited SourcePort half is tracked above.
+    WritableSourcePort: keysOf()([
+        "saveDocument",
+        "deleteDocument",
+        "listVersions",
+        "getVersion",
+        "publish",
+    ]),
+    CachePort: keysOf()([
+        "has",
+        "store",
+        "loadKey",
+        "loadAll",
+    ]),
+    ResolverPort: keysOf()([
+        "resolve",
+        "cacheKey",
+    ]),
+    ReaderPort: keysOf()([
+        "detect",
+        "read",
+        "_ownerContainer",
+    ]),
+    WriterPort: keysOf()([
+        "canWrite",
+        "write",
+        "serialize",
+    ]),
+    // The optional presentation slice KindPort extends. Py twin: the
+    // KindPresentation capability Protocol (typing-only, kept OFF the
+    // runtime_checkable KindPort so the H1 isinstance gate never requires
+    // these members) — s-dna-kindport-descriptor-schema.
+    KindPresentation: keysOf()([
+        "docs",
+        "descriptionFallbackField",
+        "uiSchema",
+        "graphStyle",
+        "asciiIcon",
+        "displayLabel",
+        "visibleInBackend",
+        "preview",
+        "graphMeta",
+    ]),
+    KindPort: keysOf()([
+        "apiVersion",
+        "kind",
+        "alias",
+        "origin",
+        "scope",
+        "isRoot",
+        "isPromptTarget",
+        "promptTargetPriority",
+        "flattenInContext",
+        "storage",
+        "isRuntimeArtifact",
+        "isSchemaAffecting",
+        "isOverlayable",
+        "scopeInheritable",
+        "plane",
+        "depFilters",
+        "getDefaultAgentName",
+        "getLayerPolicies",
+        "parse",
+        "describe",
+        "summary",
+        "promptTemplate",
+        "schema",
+        "dependencies",
+        // Inherited KindPresentation slice (keyof includes extends-members;
+        // the exhaustive binder requires listing them here too).
+        "docs",
+        "descriptionFallbackField",
+        "uiSchema",
+        "graphStyle",
+        "asciiIcon",
+        "displayLabel",
+        "visibleInBackend",
+        "preview",
+        "graphMeta",
+    ]),
+    ToolPort: keysOf()([
+        "name",
+        "group",
+        "description",
+        "summary",
+        "argsSchema",
+        "hitl",
+        "scope",
+        "source",
+        "getCallable",
+    ]),
+    ExtensionHost: keysOf()([
+        "hooks",
+        "kind",
+        "kindFromDescriptor",
+        "reader",
+        "writer",
+        "on",
+        "onVeto",
+        "tool",
+        "compositionProfile",
+    ]),
+    Extension: keysOf()([
+        "name",
+        "version",
+        "register",
+        "templates",
+    ]),
+    RecordSearchProvider: keysOf()([
+        "search",
+    ]),
+    EmbeddingPort: keysOf()([
+        "modelId",
+        "dims",
+        "embed",
+    ]),
+    SourceCapabilities: keysOf()([
+        "source",
+        "drafts",
+        "versions",
+        "layers",
+        "bundleRead",
+        "bundleWrite",
+        "kernelAttachable",
+        "granularList",
+        "granularOne",
+        "queryPushdown",
+    ]),
+    // Interface NAMES (see CapabilityProtocolsProof above for the
+    // compile-time existence binding).
+    CapabilityProtocols: [
+        "BundleEntryReadable",
+        "KernelAttachable",
+        "Versionable",
+    ],
+};

package/dist/kernel/preview.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Document preview API.
+ *
+ * The Studio's "preview" pane consumes structured `PreviewBlock`s instead
+ * of raw markdown so each kind can render however makes sense (markdown,
+ * code, tabular fields). The polymorphism lives inside each KindPort
+ * (`KindPort.preview?`); this module is only the type definition,
+ * generic fallback, and a cross-document consumer scan.
+ */
+import type { Document } from "./document.js";
+import type { ManifestInstance } from "./instance.js";
+/**
+ * A single renderable section of a document preview. Documents can produce
+ * multiple blocks (e.g. a Soul has SOUL.md + STYLE.md + soul.json), which
+ * the Studio renders stacked.
+ *
+ * `kind` is the renderer hint:
+ *   - "markdown"  → MarkdownBlock (prose, headings, lists)
+ *   - "code"      → CodeBlock (yaml, json, plain text in monospace)
+ *   - "fields"    → FieldsBlock (key/value pairs)
+ *   - "empty"     → no body, just the title (used for empty states)
+ */
+export type PreviewBlockKind = "markdown" | "code" | "fields" | "empty";
+export interface PreviewBlock {
+    kind: PreviewBlockKind;
+    /** Section header shown above the body. */
+    title: string;
+    /** Free-form body content. Type depends on `kind`. */
+    body?: string;
+    /** Used by code blocks to choose syntax highlighting. */
+    language?: string;
+    /** Used by fields blocks. Ordered. */
+    fields?: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+/**
+ * Last-resort renderer used by `ManifestInstance.renderDoc` when the
+ * KindPort doesn't implement `preview()`. Always returns SOMETHING so the
+ * Studio never has a blank pane — even unknown kinds get a JSON dump of
+ * their spec.
+ */
+export declare function genericSpecDump(doc: Document): PreviewBlock[];
+/**
+ * Walk every document in the manifest and return those that reference the
+ * given target via a dep_filters declaration on their KindPort.
+ *
+ * Uses `instance.iterDocDeps(doc)` under the hood — the kernel method
+ * that dynamically walks `KindPort.depFilters()` for each doc. No
+ * hardcoded field-to-kind map needed; any extension that declares its
+ * deps via depFilters participates automatically.
+ */
+export declare function findConsumers(instance: ManifestInstance, target: {
+    kind: string;
+    name: string;
+}): Array<{
+    kind: string;
+    name: string;
+}>;

package/dist/kernel/preview.js

@@ -0,0 +1,54 @@
+/**
+ * Last-resort renderer used by `ManifestInstance.renderDoc` when the
+ * KindPort doesn't implement `preview()`. Always returns SOMETHING so the
+ * Studio never has a blank pane — even unknown kinds get a JSON dump of
+ * their spec.
+ */
+export function genericSpecDump(doc) {
+    const spec = (doc.spec ?? {});
+    if (!spec || Object.keys(spec).length === 0) {
+        return [{ kind: "empty", title: `${doc.kind} (empty spec)` }];
+    }
+    return [
+        {
+            kind: "code",
+            title: `${doc.kind} spec`,
+            body: JSON.stringify(spec, null, 2),
+            language: "json",
+        },
+    ];
+}
+/**
+ * Walk every document in the manifest and return those that reference the
+ * given target via a dep_filters declaration on their KindPort.
+ *
+ * Uses `instance.iterDocDeps(doc)` under the hood — the kernel method
+ * that dynamically walks `KindPort.depFilters()` for each doc. No
+ * hardcoded field-to-kind map needed; any extension that declares its
+ * deps via depFilters participates automatically.
+ */
+export function findConsumers(instance, target) {
+    const out = [];
+    const seen = new Set();
+    const iterFn = instance.iterDocDeps;
+    for (const doc of instance.documents) {
+        if (doc.kind === target.kind && doc.name === target.name)
+            continue;
+        const deps = iterFn?.call(instance, doc) ?? [];
+        let hit = false;
+        for (const dep of deps) {
+            if (dep.targetKind !== target.kind)
+                continue;
+            if (dep.names.includes(target.name)) {
+                hit = true;
+                break;
+            }
+        }
+        const key = `${doc.kind}/${doc.name}`;
+        if (hit && !seen.has(key)) {
+            seen.add(key);
+            out.push({ kind: doc.kind, name: doc.name });
+        }
+    }
+    return out;
+}

package/dist/kernel/prompt-budget.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Prompt-budget estimation + enforcement helpers.
+ *
+ * 1:1 parity with Python `dna/kernel/prompt_budget.py`.
+ *
+ * Conservative token estimator + instruction-budget evaluator used by the
+ * write-path guard (`src/extensions/helix/write-guards.ts` ::
+ * promptBudgetGuard) that blocks a strict/voice Agent whose instruction
+ * exceeds its model's `instruction_token_cap`.
+ *
+ * CONTRACT — never hardcode token caps: the cap the evaluator receives
+ * ALWAYS comes from the ModelProfile registry
+ * (`kernel.modelProfile(idOrAlias)`), never from a literal in code.
+ * Motivated by a real outage: a 17269-token voice persona silently
+ * exceeded the realtime model's 16384-token session-instructions cap.
+ */
+/** Conservative (over-counts); mirrors the Python CHARS_PER_TOKEN. */
+export declare const CHARS_PER_TOKEN = 3.5;
+export declare class PromptBudgetExceededError extends Error {
+    readonly modelId: string;
+    readonly estimatedTokens: number;
+    readonly cap: number;
+    readonly agentName: string;
+    constructor(opts: {
+        modelId: string;
+        estimatedTokens: number;
+        cap: number;
+        agentName: string;
+    });
+}
+export declare function estimateTokens(charCount: number): number;
+export interface BudgetVerdict {
+    exceeded: boolean;
+    estimatedTokens: number;
+    cap: number;
+}
+export declare function evaluateInstructionBudget(instruction: string, opts: {
+    cap: number;
+}): BudgetVerdict;

package/dist/kernel/prompt-budget.js

@@ -0,0 +1,43 @@
+/**
+ * Prompt-budget estimation + enforcement helpers.
+ *
+ * 1:1 parity with Python `dna/kernel/prompt_budget.py`.
+ *
+ * Conservative token estimator + instruction-budget evaluator used by the
+ * write-path guard (`src/extensions/helix/write-guards.ts` ::
+ * promptBudgetGuard) that blocks a strict/voice Agent whose instruction
+ * exceeds its model's `instruction_token_cap`.
+ *
+ * CONTRACT — never hardcode token caps: the cap the evaluator receives
+ * ALWAYS comes from the ModelProfile registry
+ * (`kernel.modelProfile(idOrAlias)`), never from a literal in code.
+ * Motivated by a real outage: a 17269-token voice persona silently
+ * exceeded the realtime model's 16384-token session-instructions cap.
+ */
+/** Conservative (over-counts); mirrors the Python CHARS_PER_TOKEN. */
+export const CHARS_PER_TOKEN = 3.5;
+export class PromptBudgetExceededError extends Error {
+    modelId;
+    estimatedTokens;
+    cap;
+    agentName;
+    constructor(opts) {
+        super(`Agent '${opts.agentName}' instruction is ~${opts.estimatedTokens} tokens, ` +
+            `over the ${opts.cap}-token instruction cap of model '${opts.modelId}'. ` +
+            `Trim the instruction or move detail to tool-discoverable docs. ` +
+            `(The cap comes from the model's ModelProfile doc — update the ` +
+            `profile if the model's real cap changed; never hardcode caps.)`);
+        this.name = "PromptBudgetExceededError";
+        this.modelId = opts.modelId;
+        this.estimatedTokens = opts.estimatedTokens;
+        this.cap = opts.cap;
+        this.agentName = opts.agentName;
+    }
+}
+export function estimateTokens(charCount) {
+    return Math.ceil(charCount / CHARS_PER_TOKEN);
+}
+export function evaluateInstructionBudget(instruction, opts) {
+    const tok = estimateTokens((instruction ?? "").length);
+    return { exceeded: tok > opts.cap, estimatedTokens: tok, cap: opts.cap };
+}

package/dist/kernel/prompt-builder.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PromptBuilder — namespace class extracting prompt-related logic
+ * from ManifestInstance.
+ *
+ * Usage: `mi.prompt.build()` — equivalent to `mi.buildPrompt()`.
+ *
+ * This is an extraction (Chunk 2 of the kernel simplification plan).
+ * The original methods on ManifestInstance are preserved; both APIs
+ * return identical results.
+ */
+import type { ManifestInstance, BuildPromptOpts } from "./instance.js";
+export declare class PromptBuilder {
+    private host;
+    constructor(host: ManifestInstance);
+    /**
+     * Build the final prompt string for the given (or default) agent.
+     * Equivalent to `mi.buildPrompt(opts)`.
+     */
+    build(opts?: BuildPromptOpts): Promise<string>;
+    private _findAgent;
+    private _buildContext;
+    private _renderPrompt;
+    private _mustacheRender;
+    private static _getDescription;
+}