dna-sdk 0.1.0

package/dist/extensions/federation.js

@@ -0,0 +1,173 @@
+/**
+ * FederationExtension — Phase 14r MCP Federation (schema v2, 2026-07-07).
+ *
+ * Declares the `MCPFederation` Kind: an external MCP server whose tools
+ * DNA agents consume via `Agent.spec.mcp_servers` (primary,
+ * s-mcp-servers-on-agent) or via the DNA-as-MCP-server proxy
+ * (legacy Phase 14r direction). Transports: stdio | streamable_http.
+ * Auth carries env-var NAMES only — never secret values.
+ *
+ * Schema v2 is fully backward-compatible with v1 docs: `transport`
+ * defaults to `stdio` and every new field is optional.
+ *
+ * 1:1 parity with python/dna/extensions/federation/__init__.py.
+ * The TS SDK ships schema/Kind parity only — the agent runtime (and the
+ * MCP client) is Python-only by design (spec §3).
+ */
+import { KindBase } from "../kernel/kind_base.js";
+import { SD } from "../kernel/protocols.js";
+const API_VERSION = "github.com/ruinosus/dna/federation/v1";
+class MCPFederationKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "MCPFederation";
+    alias = "federation-mcp";
+    origin = "github.com/ruinosus/dna/federation";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.yaml("federations");
+    graphStyle = { fill: "#F97316", stroke: "#EA580C", textColor: "#fff" };
+    asciiIcon = "🛰️";
+    displayLabel = "MCP Federations";
+    docs = "An MCPFederation declares an external MCP server whose tools DNA " +
+        "agents consume: a Agent lists the doc's name in " +
+        "spec.mcp_servers and the harness loads the remote tools as " +
+        "first-class agent tools (zero code, zero deploy). Transports: " +
+        "stdio (command/args/env/cwd) or streamable_http (url). Auth " +
+        "carries env-var NAMES only — never secret values. allowed_tools " +
+        "bounds what any agent can get; enabled: false is the declarative " +
+        "kill-switch. Docs in _lib/federations/ are inherited by every " +
+        "scope. Also consumed by the DNA-as-MCP-server proxy (Phase 14r).";
+    dependencies() { return null; }
+    schema() {
+        // v2 (spec 2026-07-07-mcp-first-tools-design.md §5.1). Back-compat:
+        // every v1 doc (required command, stdio implied) stays valid —
+        // transport defaults to stdio and command is enforced for stdio
+        // (resp. url for streamable_http) via allOf/if-then instead of a
+        // top-level required: [command].
+        return {
+            type: "object",
+            additionalProperties: true,
+            properties: {
+                transport: {
+                    type: "string",
+                    enum: ["stdio", "streamable_http"],
+                    default: "stdio",
+                    description: "How to reach the server: stdio subprocess (default, v1) or Streamable HTTP.",
+                },
+                url: {
+                    type: "string",
+                    description: "Server endpoint. Required when transport=streamable_http.",
+                },
+                command: {
+                    type: "string",
+                    description: "Executable to run (resolved via PATH). Required when transport=stdio.",
+                },
+                args: { type: "array", items: { type: "string" }, default: [] },
+                env: {
+                    type: "object",
+                    additionalProperties: { type: "string" },
+                    default: {},
+                    description: "Extra env vars merged onto os.environ for the subprocess.",
+                },
+                cwd: {
+                    type: ["string", "null"],
+                    description: "Working directory; null = scope dir.",
+                },
+                tool_prefix: {
+                    type: "string",
+                    description: "Prepended to every proxied tool name (e.g. 'graphify_').",
+                    default: "",
+                },
+                enabled: {
+                    type: "boolean",
+                    default: true,
+                    description: "Disable without deleting the doc — declarative kill-switch, no deploy.",
+                },
+                allowed_tools: {
+                    type: "array",
+                    items: { type: "string" },
+                    default: [],
+                    description: "Server-level allowlist of remote tool names (pre-prefix). Empty = all.",
+                },
+                timeout_s: {
+                    type: "integer",
+                    default: 30,
+                    description: "Per-call timeout default (seconds). Per-agent entry may override.",
+                },
+                auth: {
+                    type: "object",
+                    additionalProperties: false,
+                    description: "Auth by env-var NAME — the value is read from the process env at connect time and never stored in docs, logs, or events.",
+                    properties: {
+                        kind: {
+                            type: "string",
+                            enum: ["none", "bearer_env", "header_env"],
+                            default: "none",
+                        },
+                        env: {
+                            type: "string",
+                            description: "Name of the env var holding the secret value.",
+                        },
+                        header: {
+                            type: "string",
+                            description: "Header to carry the value (header_env only; bearer_env implies Authorization: Bearer).",
+                        },
+                    },
+                },
+                propagate_tenant: {
+                    type: "boolean",
+                    default: true,
+                    description: "HTTP transport: stamp X-DNA-Tenant-Effective / X-DNA-Scope / X-DNA-Agent headers.",
+                },
+                health_check: {
+                    type: "object",
+                    additionalProperties: true,
+                    properties: {
+                        interval_s: { type: "integer", default: 30 },
+                        timeout_s: { type: "integer", default: 5 },
+                    },
+                },
+                tags: { type: "array", items: { type: "string" }, default: [] },
+            },
+            allOf: [
+                {
+                    // NOTE: required: [transport] inside the `if` is load-bearing —
+                    // without it an absent `transport` matches the const vacuously
+                    // and v1 docs would be forced to carry `url`.
+                    if: {
+                        properties: { transport: { const: "streamable_http" } },
+                        required: ["transport"],
+                    },
+                    then: { required: ["url"] },
+                    else: { required: ["command"] },
+                },
+            ],
+        };
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        const transport = spec.transport || "stdio";
+        const target = (transport === "streamable_http" ? spec.url : spec.command) ?? "?";
+        const prefix = spec.tool_prefix ?? "";
+        return `${target || "?"} (${prefix || "no-prefix"})`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        return {
+            transport: spec.transport || "stdio",
+            url: spec.url ?? "",
+            command: spec.command ?? "",
+            tool_prefix: spec.tool_prefix ?? "",
+            enabled: spec.enabled ?? true,
+            tags: spec.tags ?? [],
+        };
+    }
+}
+export class FederationExtension {
+    name = "federation";
+    version = "1.0.0";
+    register(kernel) {
+        kernel.kind(new MCPFederationKind());
+    }
+}

package/dist/extensions/guardrails/DOCS.md

@@ -0,0 +1,20 @@
+# Guardrail
+
+A Guardrail declares a hard safety, compliance, or policy rule that must be
+enforced on every turn of an agent's conversation. It is stored as a bundle
+rooted on a `GUARDRAIL.md` marker file.
+
+Unlike Skills (which are on-demand procedural know-how), Guardrails are
+flattened directly into the agent's system prompt so the rules are always in
+view. Each Guardrail carries a `severity` (`low`, `medium`, `high`, `critical`)
+and a list of `rules` that the Agent template renders inline.
+
+**Helix-native kind — not guardrails.ai.** This is not a binding for the
+`guardrails.ai` runtime validator library. It is inspired by the tripwire /
+input-output guardrail pattern from the OpenAI Agents SDK
+(https://openai.github.io/openai-agents-python/guardrails/) but implemented
+natively as a composable document kind. No external runtime is required;
+enforcement is purely prompt-level.
+
+**Composition:** referenced by Agents via `dep_filters.guardrails`
+(alias `guardrails-guardrail`).

package/dist/extensions/guardrails.d.ts

@@ -0,0 +1,31 @@
+/**
+ * GuardrailExtension — Guardrail kind + GuardrailReader + GuardrailWriter.
+ *
+ * 1:1 parity with Python dna.v3.extensions.guardrails.
+ */
+import type { BundleHandle } from "../kernel/bundle-handle.js";
+import type { FSLike } from "../kernel/fs.js";
+import type { ExtensionHost, Extension, ReaderPort, SerializedFile, WriterPort } from "../kernel/protocols.js";
+export declare class GuardrailReader implements ReaderPort {
+    private fs;
+    constructor(fs?: FSLike);
+    detect(bundle: BundleHandle): boolean;
+    read(bundle: BundleHandle): Record<string, unknown>;
+}
+export declare class GuardrailWriter implements WriterPort {
+    private fs;
+    constructor(fs?: FSLike);
+    canWrite(raw: Record<string, unknown>): boolean;
+    /** Shared by write()/serialize() so the two surfaces cannot drift
+     *  (s-dna-rw-roundtrip-suite). */
+    private entries;
+    serialize(raw: Record<string, unknown>): SerializedFile[];
+    write(bundle: BundleHandle, raw: Record<string, unknown>): void;
+}
+export declare class GuardrailExtension implements Extension {
+    private fs;
+    readonly name = "guardrails";
+    readonly version = "1.0.0";
+    constructor(fs?: FSLike);
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/guardrails.js

@@ -0,0 +1,228 @@
+/**
+ * GuardrailExtension — Guardrail kind + GuardrailReader + GuardrailWriter.
+ *
+ * 1:1 parity with Python dna.v3.extensions.guardrails.
+ */
+import yaml from "js-yaml";
+import { nodeFS } from "../kernel/fs.js";
+import { KindBase } from "../kernel/kind_base.js";
+import { GuardrailSchema, GuardrailSpecSchema, zodSpecToJsonSchema } from "../kernel/models.js";
+import { SD } from "../kernel/protocols.js";
+// ---------------------------------------------------------------------------
+// GuardrailKind
+// ---------------------------------------------------------------------------
+class GuardrailKind extends KindBase {
+    apiVersion = "github.com/ruinosus/dna/v1";
+    kind = "Guardrail";
+    alias = "guardrails-guardrail";
+    isSchemaAffecting = true;
+    origin = "github.com/ruinosus/dna/guardrails";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    descriptionFallbackField = "instruction";
+    storage = SD.bundle("guardrails", "GUARDRAIL.md", "list", "rules");
+    graphStyle = { fill: "#EF4444", stroke: "#DC2626", textColor: "#fff" };
+    asciiIcon = "🛡️";
+    displayLabel = "Guardrails";
+    _sourceUrl = import.meta.url;
+    docs = "A Guardrail declares a hard safety, compliance, or policy rule " +
+        "enforced on every agent turn. Stored as a bundle rooted on " +
+        "GUARDRAIL.md. Flattened directly into the system prompt — helix- " +
+        "native, inspired by OpenAI Agents SDK tripwires, not guardrails.ai.";
+    uiSchema = {
+        instruction: {
+            widget: "markdown",
+            label: "GUARDRAIL.md",
+            help: "Prose body explaining the intent behind the rule set.",
+            height: 280,
+            order: 10,
+        },
+        rules: {
+            widget: "list-markdown",
+            label: "Rules",
+            help: "Individual directives the agent must follow every turn.",
+            order: 20,
+        },
+        severity: {
+            widget: "select",
+            label: "Severity",
+            help: "warn lets the turn continue; error fails the turn; hard refuses to answer.",
+            order: 30,
+        },
+        scope: {
+            widget: "select",
+            label: "Scope",
+            help: "input guards the user prompt; output guards the agent response; both runs on each side.",
+            order: 40,
+        },
+    };
+    schema() { return zodSpecToJsonSchema(GuardrailSpecSchema); }
+    parse(raw) {
+        return GuardrailSchema.parse(raw);
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        return {
+            severity: typeof spec.severity === "string" ? spec.severity : "warn",
+            scope: typeof spec.scope === "string" ? spec.scope : "both",
+            rules: Array.isArray(spec.rules) ? spec.rules.length : 0,
+        };
+    }
+    preview(doc) {
+        const spec = (doc.spec ?? {});
+        const blocks = [];
+        const instruction = typeof spec.instruction === "string" ? spec.instruction : "";
+        if (instruction) {
+            blocks.push({ kind: "markdown", title: "GUARDRAIL.md", body: instruction });
+        }
+        const rules = spec.rules;
+        if (Array.isArray(rules) && rules.length > 0) {
+            blocks.push({
+                kind: "markdown",
+                title: "Rules",
+                body: rules
+                    .map((r) => `- ${typeof r === "string" ? r : JSON.stringify(r)}`)
+                    .join("\n"),
+            });
+        }
+        const meta = [];
+        if (typeof spec.severity === "string")
+            meta.push({ label: "severity", value: spec.severity });
+        if (typeof spec.scope === "string")
+            meta.push({ label: "scope", value: spec.scope });
+        if (meta.length > 0) {
+            blocks.push({ kind: "fields", title: "Policy", fields: meta });
+        }
+        if (blocks.length === 0) {
+            return [{ kind: "empty", title: "Guardrail (empty)" }];
+        }
+        return blocks;
+    }
+}
+// ---------------------------------------------------------------------------
+// GuardrailReader
+// ---------------------------------------------------------------------------
+function parseFrontmatter(text) {
+    const match = text.match(/^---\n([\s\S]*?)---\n?/);
+    if (!match)
+        return {};
+    try {
+        const parsed = yaml.load(match[1]);
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export class GuardrailReader {
+    fs;
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    detect(bundle) {
+        const path = bundle.path ?? "";
+        return this.fs.exists(`${path}/GUARDRAIL.md`);
+    }
+    read(bundle) {
+        const path = bundle.path ?? "";
+        const guardrailMd = this.fs.readFile(`${path}/GUARDRAIL.md`);
+        const metadata = parseFrontmatter(guardrailMd);
+        const name = String(metadata.name || "") || path.split("/").pop() || "";
+        const description = String(metadata.desc || metadata.description || "");
+        const severity = String(metadata.severity || "warn");
+        const scope = String(metadata.scope || "both");
+        // Extract body (after frontmatter)
+        const body = guardrailMd.replace(/^---\n[\s\S]*?---\n?/, "").trim();
+        // Parse rules from body: lines starting with "- "
+        const bodyRules = [];
+        for (const line of body.split("\n")) {
+            const trimmed = line.trimStart();
+            if (trimmed.startsWith("- ")) {
+                bodyRules.push(trimmed.slice(2).trim());
+            }
+        }
+        // Rules can come from frontmatter (YAML list) or body (markdown list)
+        const frontmatterRules = metadata.rules;
+        let rules;
+        if (Array.isArray(frontmatterRules) && frontmatterRules.length > 0) {
+            rules = frontmatterRules.map(String);
+        }
+        else {
+            rules = bodyRules;
+        }
+        return {
+            apiVersion: "github.com/ruinosus/dna/v1",
+            kind: "Guardrail",
+            metadata: { name, description },
+            spec: { rules, severity, scope },
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// GuardrailWriter
+// ---------------------------------------------------------------------------
+export class GuardrailWriter {
+    fs;
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    canWrite(raw) {
+        return raw.kind === "Guardrail";
+    }
+    /** Shared by write()/serialize() so the two surfaces cannot drift
+     *  (s-dna-rw-roundtrip-suite). */
+    entries(raw, defaultName) {
+        const spec = raw.spec ?? {};
+        const meta = raw.metadata ?? {};
+        const name = meta.name || defaultName;
+        const description = meta.description ?? "";
+        const severity = spec.severity ?? "warn";
+        const scope = spec.scope ?? "both";
+        const rules = spec.rules ?? [];
+        // Build frontmatter lines
+        const fmLines = [];
+        fmLines.push(`name: ${name}`);
+        if (description)
+            fmLines.push(`desc: ${description}`);
+        // Only write severity/scope if non-default
+        if (severity !== "warn")
+            fmLines.push(`severity: ${severity}`);
+        if (scope !== "both")
+            fmLines.push(`scope: ${scope}`);
+        const frontmatter = fmLines.join("\n");
+        // Build body: rules as "- " lines
+        const bodyLines = rules.map((r) => `- ${r}`);
+        const body = bodyLines.join("\n");
+        const content = body
+            ? `---\n${frontmatter}\n---\n\n${body}\n`
+            : `---\n${frontmatter}\n---\n`;
+        return [{ relativePath: "GUARDRAIL.md", content }];
+    }
+    serialize(raw) {
+        return this.entries(raw, "");
+    }
+    write(bundle, raw) {
+        const path = bundle.path ?? "";
+        this.fs.mkdir(path);
+        for (const f of this.entries(raw, path.split("/").pop() || "")) {
+            this.fs.writeFile(`${path}/${f.relativePath}`, f.content ?? "");
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export class GuardrailExtension {
+    fs;
+    name = "guardrails";
+    version = "1.0.0";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    register(kernel) {
+        kernel.kind(new GuardrailKind());
+        kernel.reader(new GuardrailReader(this.fs));
+        kernel.writer(new GuardrailWriter(this.fs));
+    }
+}

package/dist/extensions/helix/DOCS-Actor.md

@@ -0,0 +1,20 @@
+# Actor
+
+An Actor is a UML-canonical participant in the system — a human user, an
+external system, or a time/schedule trigger. Actors describe WHO or WHAT
+initiates or collaborates with agents, separating role identity from the
+agents that fulfill that role. Canonical api version:
+`github.com/ruinosus/dna/v1`.
+
+**Actor types.** The `actorType` field disambiguates:
+- `human` — a person or role (e.g. "support specialist", "admin")
+- `system` — an upstream service or external system triggering behavior
+- `time` — a scheduled or cron-like trigger
+
+**Composition.** Actors are referenced by UseCases (as `primary_actor` and
+`supporting_actors`) and by Agents through `dep_filters.actors`.
+Actors are NOT prompt targets on their own — they are structural metadata
+that lets manifests document and wire the cast of characters around an
+agent without embedding role descriptions in prompts.
+
+**Storage.** Flat YAML file at `actors/<name>.yaml`.

package/dist/extensions/helix/DOCS-Agent.md

@@ -0,0 +1,20 @@
+# Agent
+
+A Agent is the primary prompt target in a helix manifest — it is
+what actually runs when a user (or another agent) talks to the system. It
+carries an `instruction` (the agent's main prompt, usually a bundled
+`AGENT.md`), a `model` to call, and `dep_filters` that declare which Soul,
+Skills, Guardrails, and Actors it composes with.
+
+**Prompt assembly.** Every turn the kernel builds the agent's system prompt
+by rendering the `prompt_template`: the instruction body comes first, then
+the Soul content (flattened in full), then each Guardrail (name, severity,
+and rules). Skills are deliberately NOT flattened — they are exposed via
+Agent Skills progressive disclosure so the context window stays lean.
+
+**Priority.** `prompt_target_priority = 10` means Agent wins over
+other prompt-target kinds when the harness has to pick one to run.
+
+**Storage.** Bundle-based: `agents/<name>/AGENT.md` with optional
+`scripts/`, `references/`, and `assets/` subdirectories. Canonical api
+version: `github.com/ruinosus/dna/v1`.

package/dist/extensions/helix/DOCS-UseCase.md

@@ -0,0 +1,20 @@
+# UseCase
+
+A UseCase is a UML-canonical use case document: a goal-oriented interaction
+between one or more Actors and the system. It composes a primary actor,
+supporting actors, and the agent(s) that fulfill the goal, then carries the
+classical UML fields: `preconditions`, `main_flow`, `alternate_flows`,
+`postconditions`, and `success_criteria`. Canonical api version:
+`github.com/ruinosus/dna/v1`.
+
+**Not a prompt target.** A UseCase is purely declarative — it documents how
+the manifest's agents and actors are meant to work together to achieve a
+business goal. It is structural composition metadata, consumed by tooling
+(navigators, doc generators, validators) rather than by the LLM directly.
+
+**When to use.** Reach for UseCases when a helix manifest is complex
+enough that the relationship between actors and agents is non-obvious, or
+when you need machine-readable traceability from requirements to the agents
+that implement them.
+
+**Storage.** Flat YAML file at `use_cases/<name>.yaml`.

package/dist/extensions/helix/layers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DEPRECATED shim — DefaultLayerResolver moved into the kernel.
+ *
+ * Layer resolution is a core kernel responsibility
+ * (s-invert-layer-resolver-dep, 2026-07-07): the kernel must work with
+ * zero extensions loaded, so the resolver now lives at
+ * `src/kernel/layer-resolver.ts`. This module reexports the old public
+ * names for external importers and emits a DeprecationWarning on import.
+ *
+ * @deprecated Import from `dna-sdk/kernel/layer-resolver` instead.
+ */
+export { DefaultLayerResolver, deepMerge, mergeTimelineArrays, type LayerSource, } from "../../kernel/layer-resolver.js";

package/dist/extensions/helix/layers.js

@@ -0,0 +1,18 @@
+/**
+ * DEPRECATED shim — DefaultLayerResolver moved into the kernel.
+ *
+ * Layer resolution is a core kernel responsibility
+ * (s-invert-layer-resolver-dep, 2026-07-07): the kernel must work with
+ * zero extensions loaded, so the resolver now lives at
+ * `src/kernel/layer-resolver.ts`. This module reexports the old public
+ * names for external importers and emits a DeprecationWarning on import.
+ *
+ * @deprecated Import from `dna-sdk/kernel/layer-resolver` instead.
+ */
+export { DefaultLayerResolver, deepMerge, mergeTimelineArrays, } from "../../kernel/layer-resolver.js";
+// Node/Bun idiomatic import-time deprecation (parity with the Python
+// shim's warnings.warn(DeprecationWarning)).
+if (typeof process !== "undefined" && typeof process.emitWarning === "function") {
+    process.emitWarning("extensions/helix/layers is deprecated — import DefaultLayerResolver/" +
+        "deepMerge from kernel/layer-resolver instead (s-invert-layer-resolver-dep).", "DeprecationWarning");
+}

package/dist/extensions/helix/write-guards.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Helix-owned write-path guards (s-write-path-despecialize).
+ *
+ * These rules used to live inline in `Kernel.writeDocument` as
+ * `kind === "Agent"` special-cases — extension domain knowledge
+ * leaked into the microkernel. They are now `pre_save` VETO hooks
+ * registered by `HelixExtension.register` (the Agent owner):
+ *
+ * - platform-agent fork guard (priority 10) — no per-tenant overlay of a
+ *   `_lib` Agent (JARVIS 16384 outage, 2026-05-29).
+ * - prompt-budget enforcement (priority 20) — an Agent whose instruction
+ *   exceeds its model's `instruction_token_cap` (read from the
+ *   ModelProfile registry — never hardcode token caps) is blocked when
+ *   the model is strict (voice persona / `realtime: true` profile) and
+ *   warned when it is a chat model (fail-open on unknown model / missing
+ *   cap / instruction_file).
+ * - Kind-Writer contract      (priority 30) — a Agent declaring
+ *   `writes_kind` must satisfy the slot↔schema contract at write time.
+ *
+ * A throw from a guard vetoes the write (nothing is persisted). The hooks
+ * fire for EVERY `kernel.writeDocument` regardless of `skipHooks` — they
+ * are integrity gates, not notifications.
+ *
+ * 1:1 parity with Python dna.extensions.helix.write_guards.
+ */
+import type { PreSaveContext } from "../../kernel/hooks.js";
+import type { ExtensionHost } from "../../kernel/protocols.js";
+export declare const PRIORITY_FORK_GUARD = 10;
+export declare const PRIORITY_PROMPT_BUDGET = 20;
+export declare const PRIORITY_KIND_WRITER = 30;
+/**
+ * Block per-tenant overlays of `_lib` Agents.
+ *
+ * The `_lib` scope is the shared baseline (jarvis + the 12 transversais);
+ * its Agents are edited in git + `dna doc apply --scope _lib` (base
+ * only). A per-tenant overlay silently FORKS the persona and shadows the
+ * base for that tenant's reads — the root cause of the JARVIS 16384 outage
+ * (2026-05-29) and the stale-persona bug (2026-06-14). Veto it loudly.
+ */
+export declare function platformAgentForkGuard(ctx: PreSaveContext): void;
+/**
+ * Enforce the Agent instruction budget against the ModelProfile registry.
+ *
+ * CONTRACT — never hardcode token caps: the cap ALWAYS comes from the
+ * ModelProfile registry (`kernel.modelProfile(idOrAlias)` → the
+ * `modelreg-model-profile` Kind in `_lib`), never from a literal in code.
+ *
+ * Three paths (s-tier-a-modelprofile):
+ * - VETO — strict model (voice persona, or `realtime: true` profile) and
+ *   the instruction estimate exceeds `instruction_token_cap`.
+ * - WARN — a chat Agent (`spec.model` declared, non-realtime profile)
+ *   exceeds the cap: tolerated but logged loud.
+ * - PASS — no model declared, no profile found, no cap, or within budget.
+ *   Enforcement is opt-in by DATA: writing a profile with a cap arms it.
+ *
+ * Fail-open on uncounted text (instruction_file / non-string body).
+ * `DNA_PROMPT_BUDGET_ENFORCE=0` downgrades the veto to a warn.
+ *
+ * 1:1 parity with Python `prompt_budget_guard`.
+ */
+export declare function promptBudgetGuard(ctx: PreSaveContext): Promise<void>;
+export declare function kindWriterContractGuard(ctx: PreSaveContext): void;
+/**
+ * Wire the Helix write guards as `pre_save` veto hooks. Keys make the
+ * registration idempotent (re-loading the extension onto a shared
+ * HookRegistry replaces instead of stacking duplicates). Takes the
+ * `ExtensionHost` slice (s-dna-extension-host-contract) — registration
+ * goes through `kernel.hooks.onVeto` for the `key` idempotency.
+ */
+export declare function registerWriteGuards(kernel: ExtensionHost): void;