dna-sdk 0.9.0 → 0.11.0

package/dist/emit/scaffold.d.ts

@@ -0,0 +1,65 @@
+import { type EmitContext, type EmitResult, type EmitterPort } from "./index.js";
+/** Render `value` as a Python string literal that round-trips exactly. JSON
+ *  string syntax is a valid Python literal (`\n`, `\"`, `\\`, `\uXXXX`), single
+ *  line — so the emitted `INSTRUCTIONS` constant is byte-equal-recoverable. */
+export declare function pyStrLiteral(value: string): string;
+/** `kb-search` → `kb_search` — a valid Python identifier for a tool stub. */
+export declare function pyIdentifier(name: string): string;
+/** The default case classifier — read the DNA signals the ctx already carries. */
+export declare function classifyCase(ctx: EmitContext): string;
+/** Resolve a `{framework × case}` template to its Mustache source — the abstract
+ *  seam between an emitter and *where a template lives*. The MVP reads
+ *  package-data ({@link PackageDataScaffoldResolver}); a future kernel-backed
+ *  resolver returns a per-scope/per-tenant Scaffold Kind body, swappable with no
+ *  emitter change. Returns null when the source has no template for the pair. */
+export interface ScaffoldResolver {
+    resolve(framework: string, kase: string): string | null;
+}
+/** The MVP resolver: read `emit/scaffolds/<framework>/<case>.py.tmpl`. */
+export declare class PackageDataScaffoldResolver implements ScaffoldResolver {
+    resolve(framework: string, kase: string): string | null;
+}
+/** Swap the active template resolver — the seam the Scaffold-as-Kind promotion
+ *  (`s-scaffold-as-kind`) plugs into. */
+export declare function setScaffoldResolver(resolver: ScaffoldResolver): ScaffoldResolver;
+/** Resolve a `{framework × case}` template through the active resolver. */
+export declare function resolveScaffold(framework: string, kase: string): string | null;
+/** The outcome of {@link selectScaffold}: which case template to fill. */
+export interface ScaffoldChoice {
+    /** The case actually selected (a template exists for it). */
+    case: string;
+    /** The template source (Mustache). */
+    template: string;
+    /** The case the classifier requested — differs from `case` on a fallback. */
+    requested: string;
+}
+/** Pick the `{framework × case}` template for `ctx`: classify, then resolve to a
+ *  real template, falling back down the generality chain when needed. */
+export declare function selectScaffold(framework: string, ctx: EmitContext, classify?: (ctx: EmitContext) => string, resolver?: ScaffoldResolver | null): ScaffoldChoice;
+/** Base for a CODE-FIRST {@link EmitterPort}. A subclass is THIN — it declares the
+ *  framework + target ids and supplies the framework-specific template variables
+ *  ({@link renderContext}), losses, and field mapping; case selection, template
+ *  fill, and the byte-equal invariant hook are inherited. */
+export declare abstract class ScaffoldEmitter implements EmitterPort {
+    abstract readonly framework: string;
+    abstract readonly target: string;
+    readonly fileExtension: string;
+    /** Optional template-resolution override (defaults to the active resolver —
+     *  package-data today, a Scaffold Kind resolver tomorrow). */
+    readonly resolver: ScaffoldResolver | null;
+    /** Framework-specific template variables (merged over the common ones). */
+    renderContext(_ctx: EmitContext, _case: string): Record<string, unknown>;
+    /** Framework-specific de-para losses (in addition to the common ones). */
+    losses(_ctx: EmitContext, _choice: ScaffoldChoice): string[];
+    /** Field-level de-para (`dnaField -> targetField`) for reporting. */
+    mapping(): Record<string, string>;
+    /** The case classifier — override to add a framework-specific case. */
+    classify(ctx: EmitContext): string;
+    private commonContext;
+    private commonLosses;
+    emit(ctx: EmitContext): EmitResult;
+    /** Byte-equal invariant hook: read the top-level `INSTRUCTIONS = <literal>`
+     *  constant every scaffold template emits (a JSON/Python string literal on one
+     *  line), uniform across all code-first targets regardless of constructor shape. */
+    extractInstructions(artifact: string): string | null;
+}

package/dist/emit/scaffold.js

@@ -0,0 +1,179 @@
+/**
+ * `emit/scaffold` — the CODE-FIRST flavor of the {@link EmitterPort} (TS twin of
+ * python `dna.emit.scaffold`).
+ *
+ * Some runtimes have NO declarative agent format — you construct an agent object
+ * in code (OpenAI Agents SDK, LangGraph, Agno, DeepAgents all expose a simple
+ * constructor). For those the emitter must produce SOURCE CODE, and it does so by
+ * **filling a curated template**, never by generating code ad-hoc — the template
+ * captures the framework's best-practice idiom; the emitter only routes and fills.
+ *
+ * The mechanism is a template library indexed by `{framework × case}` plus a tiny
+ * case classifier:
+ *
+ *   scaffolds/<framework>/<case>.py.tmpl     // curated best-practice idiom per case
+ *   selectScaffold(framework, ctx)           // inspect ctx's DNA signals → pick a case
+ *
+ * There is deliberately NO single "one template per framework": a prompt-only, a
+ * tool-calling (ReAct), and a structured-output agent are DIFFERENT structures in
+ * the SAME framework. The classifier reads the neutral {@link EmitContext} signals
+ * (no tools → `prompt-only`; tools → `with-tools`; `outputSchema` →
+ * `structured-output`) and falls back down a generality chain when a framework
+ * does not ship a case, recording the fallback as a loss.
+ *
+ * Future direction — Scaffold as a Kind: templates are read through an abstract
+ * seam, {@link resolveScaffold} (a {@link ScaffoldResolver}), NOT a hardcoded file
+ * path. The MVP resolver reads package-data, but the seam lets a second source
+ * plug in with no change to any emitter — a first-class **Scaffold Kind** resolved
+ * by the kernel (scope-aware, tenant-overridable). Tracked as `s-scaffold-as-kind`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import Mustache from "mustache";
+import { EmitError } from "./index.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The generality fallback chain (specific → general) per requested case. */
+const FALLBACK = {
+    "structured-output": ["structured-output", "with-tools", "prompt-only"],
+    "with-tools": ["with-tools", "prompt-only"],
+    "prompt-only": ["prompt-only"],
+};
+/** Render `value` as a Python string literal that round-trips exactly. JSON
+ *  string syntax is a valid Python literal (`\n`, `\"`, `\\`, `\uXXXX`), single
+ *  line — so the emitted `INSTRUCTIONS` constant is byte-equal-recoverable. */
+export function pyStrLiteral(value) {
+    return JSON.stringify(value);
+}
+/** `kb-search` → `kb_search` — a valid Python identifier for a tool stub. */
+export function pyIdentifier(name) {
+    let ident = String(name)
+        .trim()
+        .replace(/[^0-9a-zA-Z_]/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!ident)
+        ident = "tool";
+    if (/^[0-9]/.test(ident))
+        ident = `_${ident}`;
+    return ident;
+}
+/** The default case classifier — read the DNA signals the ctx already carries. */
+export function classifyCase(ctx) {
+    if (ctx.outputSchema)
+        return "structured-output";
+    if (ctx.tools.length > 0)
+        return "with-tools";
+    return "prompt-only";
+}
+/** The MVP resolver: read `emit/scaffolds/<framework>/<case>.py.tmpl`. */
+export class PackageDataScaffoldResolver {
+    resolve(framework, kase) {
+        const path = join(HERE, "scaffolds", framework, `${kase}.py.tmpl`);
+        return existsSync(path) ? readFileSync(path, "utf-8") : null;
+    }
+}
+let activeResolver = new PackageDataScaffoldResolver();
+/** Swap the active template resolver — the seam the Scaffold-as-Kind promotion
+ *  (`s-scaffold-as-kind`) plugs into. */
+export function setScaffoldResolver(resolver) {
+    activeResolver = resolver;
+    return resolver;
+}
+/** Resolve a `{framework × case}` template through the active resolver. */
+export function resolveScaffold(framework, kase) {
+    return activeResolver.resolve(framework, kase);
+}
+/** Pick the `{framework × case}` template for `ctx`: classify, then resolve to a
+ *  real template, falling back down the generality chain when needed. */
+export function selectScaffold(framework, ctx, classify = classifyCase, resolver = null) {
+    const resolve = resolver
+        ? (f, k) => resolver.resolve(f, k)
+        : resolveScaffold;
+    const requested = classify(ctx);
+    for (const kase of FALLBACK[requested] ?? [requested]) {
+        const template = resolve(framework, kase);
+        if (template !== null)
+            return { case: kase, template, requested };
+    }
+    throw new EmitError(`no scaffold template for framework '${framework}' ` +
+        `(looked for case '${requested}' and its fallbacks)`);
+}
+/** Base for a CODE-FIRST {@link EmitterPort}. A subclass is THIN — it declares the
+ *  framework + target ids and supplies the framework-specific template variables
+ *  ({@link renderContext}), losses, and field mapping; case selection, template
+ *  fill, and the byte-equal invariant hook are inherited. */
+export class ScaffoldEmitter {
+    fileExtension = "py";
+    /** Optional template-resolution override (defaults to the active resolver —
+     *  package-data today, a Scaffold Kind resolver tomorrow). */
+    resolver = null;
+    // ── the hooks a subclass overrides ────────────────────────────────────────
+    /** Framework-specific template variables (merged over the common ones). */
+    renderContext(_ctx, _case) {
+        return {};
+    }
+    /** Framework-specific de-para losses (in addition to the common ones). */
+    losses(_ctx, _choice) {
+        return [];
+    }
+    /** Field-level de-para (`dnaField -> targetField`) for reporting. */
+    mapping() {
+        return {};
+    }
+    /** The case classifier — override to add a framework-specific case. */
+    classify(ctx) {
+        return classifyCase(ctx);
+    }
+    // ── the inherited machinery ───────────────────────────────────────────────
+    commonContext(ctx) {
+        return {
+            name: ctx.name,
+            name_literal: pyStrLiteral(ctx.name),
+            description: ctx.description,
+            has_description: Boolean(ctx.description),
+            // INSTRUCTIONS constant — byte-equal, recoverable via extractInstructions.
+            instructions_literal: pyStrLiteral(ctx.instructions),
+        };
+    }
+    commonLosses(ctx, choice) {
+        const losses = [
+            "composition structure — Soul reuse + wired Guardrails flatten to one " +
+                "`INSTRUCTIONS` string (a code-first agent has no `soul:`/`guardrails:` slot)",
+            "tenant overlay — a per-tenant persona without a fork has no code-first field",
+            "eval-as-contract — prompt invariants (EvalCases) have no code-first slot",
+        ];
+        if (choice.case !== choice.requested) {
+            losses.push(`scaffold case — the '${choice.requested}' idiom is not shipped for ` +
+                `'${this.framework}'; fell back to the '${choice.case}' template ` +
+                "(structure closest to but not identical to the requested case)");
+        }
+        return losses;
+    }
+    emit(ctx) {
+        const choice = selectScaffold(this.framework, ctx, (c) => this.classify(c), this.resolver);
+        const variables = { ...this.commonContext(ctx), ...this.renderContext(ctx, choice.case) };
+        const artifact = Mustache.render(choice.template, variables);
+        const losses = [...this.commonLosses(ctx, choice), ...this.losses(ctx, choice)];
+        return {
+            artifact,
+            target: this.target,
+            filename: `${ctx.name}.${this.fileExtension}`,
+            losses,
+            mapping: this.mapping(),
+        };
+    }
+    /** Byte-equal invariant hook: read the top-level `INSTRUCTIONS = <literal>`
+     *  constant every scaffold template emits (a JSON/Python string literal on one
+     *  line), uniform across all code-first targets regardless of constructor shape. */
+    extractInstructions(artifact) {
+        const match = artifact.match(/^INSTRUCTIONS = (.+)$/m);
+        if (!match)
+            return null;
+        try {
+            return JSON.parse(match[1]);
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/emit/scaffolds/agno/prompt-only.py.tmpl

@@ -0,0 +1,15 @@
+"""DNA-emitted Agno agent: {{name}}.
+
+Generated by `dna emit --target agno`. INSTRUCTIONS is the DNA-composed prompt
+(Soul + guardrails + instruction), carried byte-equal from the source of truth —
+edit the agent in DNA and re-emit, do not hand-edit the prompt here.
+"""
+from agno.agent import Agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+agent = Agent(
+    name={{{name_literal}}},
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    instructions=INSTRUCTIONS,
+)

package/dist/emit/scaffolds/agno/with-tools.py.tmpl

@@ -0,0 +1,23 @@
+"""DNA-emitted Agno agent (tool-calling): {{name}}.
+
+Generated by `dna emit --target agno`. INSTRUCTIONS is the DNA-composed prompt
+(Soul + guardrails + instruction), carried byte-equal. Each tool below is a STUB
+scaffolded from a DNA Tool's name + description — wire its real implementation and
+typed signature (Agno derives the tool schema from the function + docstring).
+"""
+from agno.agent import Agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+{{#tools}}
+def {{func_name}}() -> str:
+    {{{docstring_literal}}}
+    raise NotImplementedError("DNA scaffold: implement the {{name}} tool")
+
+{{/tools}}
+agent = Agent(
+    name={{{name_literal}}},
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    instructions=INSTRUCTIONS,
+    tools=[{{tool_list}}],
+)

package/dist/emit/scaffolds/deepagents/prompt-only.py.tmpl

@@ -0,0 +1,16 @@
+"""DNA-emitted DeepAgents agent: {{name}}.
+
+Generated by `dna emit --target deepagents`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal from the source of
+truth — edit the agent in DNA and re-emit, do not hand-edit the prompt here.
+`system_prompt` sits in FRONT of the deep-agent's built-in harness prompt.
+"""
+from deepagents import create_deep_agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+agent = create_deep_agent(
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[],
+    system_prompt=INSTRUCTIONS,
+)

package/dist/emit/scaffolds/deepagents/with-tools.py.tmpl

@@ -0,0 +1,22 @@
+"""DNA-emitted DeepAgents agent (tool-calling): {{name}}.
+
+Generated by `dna emit --target deepagents`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal. Each tool below is a
+STUB scaffolded from a DNA Tool's name + description — wire its real implementation
+and typed signature. `system_prompt` sits in FRONT of the deep-agent harness prompt.
+"""
+from deepagents import create_deep_agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+{{#tools}}
+def {{func_name}}() -> str:
+    {{{docstring_literal}}}
+    raise NotImplementedError("DNA scaffold: implement the {{name}} tool")
+
+{{/tools}}
+agent = create_deep_agent(
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[{{tool_list}}],
+    system_prompt=INSTRUCTIONS,
+)

package/dist/emit/scaffolds/langgraph/prompt-only.py.tmpl

@@ -0,0 +1,16 @@
+"""DNA-emitted LangGraph ReAct agent: {{name}}.
+
+Generated by `dna emit --target langgraph`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal from the source of
+truth — edit the agent in DNA and re-emit, do not hand-edit the prompt here.
+"""
+from langgraph.prebuilt import create_react_agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+agent = create_react_agent(
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[],
+    prompt=INSTRUCTIONS,
+{{#has_name}}    name={{{name_literal}}},
+{{/has_name}})

package/dist/emit/scaffolds/langgraph/with-tools.py.tmpl

@@ -0,0 +1,25 @@
+"""DNA-emitted LangGraph ReAct agent (tool-calling): {{name}}.
+
+Generated by `dna emit --target langgraph`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal. Each @tool below is
+a STUB scaffolded from a DNA Tool's name + description — wire its real
+implementation and typed signature (LangChain derives the tool schema from them).
+"""
+from langchain_core.tools import tool
+from langgraph.prebuilt import create_react_agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+{{#tools}}
+@tool
+def {{func_name}}() -> str:
+    {{{docstring_literal}}}
+    raise NotImplementedError("DNA scaffold: implement the {{name}} tool")
+
+{{/tools}}
+agent = create_react_agent(
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[{{tool_list}}],
+    prompt=INSTRUCTIONS,
+{{#has_name}}    name={{{name_literal}}},
+{{/has_name}})

package/dist/emit/scaffolds/openai-agents/prompt-only.py.tmpl

@@ -0,0 +1,15 @@
+"""DNA-emitted OpenAI Agents SDK agent: {{name}}.
+
+Generated by `dna emit --target openai-agents`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal from the source of
+truth — edit the agent in DNA and re-emit, do not hand-edit the prompt here.
+"""
+from agents import Agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+agent = Agent(
+    name={{{name_literal}}},
+    instructions=INSTRUCTIONS,
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}})

package/dist/emit/scaffolds/openai-agents/with-tools.py.tmpl

@@ -0,0 +1,24 @@
+"""DNA-emitted OpenAI Agents SDK agent (tool-calling / ReAct): {{name}}.
+
+Generated by `dna emit --target openai-agents`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal. Each @function_tool
+below is a STUB scaffolded from a DNA Tool's name + description — wire its real
+implementation and typed signature (the SDK derives the tool schema from them).
+"""
+from agents import Agent, function_tool
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+{{#tools}}
+@function_tool
+def {{func_name}}() -> str:
+    {{{docstring_literal}}}
+    raise NotImplementedError("DNA scaffold: implement the {{name}} tool")
+
+{{/tools}}
+agent = Agent(
+    name={{{name_literal}}},
+    instructions=INSTRUCTIONS,
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[{{tool_list}}],
+)

package/dist/emit/vertex.d.ts

@@ -16,4 +16,7 @@ export declare class VertexEmitter implements EmitterPort {
      *  time, not part of this object. */
     toAgentConfig(ctx: EmitContext): Record<string, unknown>;
     emit(ctx: EmitContext): EmitResult;
+    /** Byte-equal invariant hook: read `instruction` back from the emitted ADK
+     *  Agent Config YAML (the `# yaml-language-server` header is a YAML comment). */
+    extractInstructions(artifact: string): string | null;
 }

package/dist/emit/vertex.js

@@ -152,4 +152,11 @@ export class VertexEmitter {
             mapping,
         };
     }
+    /** Byte-equal invariant hook: read `instruction` back from the emitted ADK
+     *  Agent Config YAML (the `# yaml-language-server` header is a YAML comment). */
+    extractInstructions(artifact) {
+        const config = yaml.load(artifact);
+        const value = config?.instruction;
+        return typeof value === "string" ? value : null;
+    }
 }

package/dist/extensions/cloud/kinds/tenant-plan.kind.yaml

@@ -0,0 +1,105 @@
+# TenantPlan — the DNA Cloud tenant→Tier assignment (record plane).
+# One doc per tenant maps it to its CURRENT Tier (free/pro/enterprise) as
+# first-class GLOBAL data, so enforcement follows billing state without a
+# redeploy. This is the billing→enforcement BRIDGE: dna-cloud's Stripe webhook
+# writes this doc on subscribe/cancel, and the MCP server reads it via
+# kernel.tenant_plan(tenant) when a token carries no explicit plan claim.
+#
+# CONTRACT — the OSS SDK only READS: zero Stripe/billing code lives here. The
+# SDK resolves tier_id from THIS doc; dna-cloud (closed source) is the only
+# writer. A missing TenantPlan is not an error — the MCP guard falls back to the
+# Free floor.
+#
+# TenantPlans live in the `_lib` scope (`tenant-plans/<tenant>.yaml`) —
+# TenantPlan is GLOBAL (base only, no per-tenant override) and NOT inheritable;
+# kernel.tenant_plan() queries `_lib` directly regardless of the caller's scope.
+#
+# PARITY-CRITICAL package data: the byte-identical mirror lives at
+# packages/sdk-{py,ts}/{dna/extensions,src/extensions}/cloud/kinds/
+# tenant-plan.kind.yaml (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: tenant-plan
+spec:
+  target_api_version: github.com/ruinosus/dna/cloud/v1
+  target_kind: TenantPlan
+  alias: cloud-tenant-plan
+  origin: github.com/ruinosus/dna/cloud
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: tenant-plans
+  schema:
+    type: object
+    additionalProperties: false
+    required:
+    - tenant
+    - tier_id
+    properties:
+      tenant:
+        type: string
+        description: The DNA tenant this assignment is for. The doc name SHOULD
+          equal the tenant; kernel.tenant_plan() matches on this field.
+      tier_id:
+        type: string
+        description: The assigned Tier's id, e.g. free, pro, enterprise. Resolved
+          to caps via kernel.tier(tier_id) — never a literal in code.
+      source:
+        type: string
+        description: Where the assignment came from, e.g. stripe / manual / trial.
+      stripe_customer_id:
+        type: string
+        description: The Stripe customer id backing the assignment (dna-cloud
+          writes it; the OSS SDK never calls Stripe).
+      stripe_subscription_id:
+        type: string
+        description: The Stripe subscription id backing the assignment (dna-cloud
+          writes it; the OSS SDK never calls Stripe).
+      status:
+        type: string
+        description: The billing status of the assignment, e.g. active / past_due
+          / canceled.
+      updated_at:
+        type: string
+        format: date-time
+        description: When dna-cloud last wrote this assignment (ISO 8601).
+      notes:
+        type:
+        - string
+        - 'null'
+        description: Free-form operator notes.
+  describe: '{tenant} → {tier_id}'
+  summary:
+    tenant: ''
+    tier_id: ''
+    status: ''
+  ui:
+    mode: govern
+    label:
+      en: Tenant Plans
+      pt-BR: Planos por Tenant
+    icon: 🎫
+    description:
+      en: DNA Cloud tenant→Tier assignments (billing→enforcement bridge).
+      pt-BR: Atribuições tenant→Tier do DNA Cloud (ponte cobrança→enforcement).
+    routes:
+      list: docs/TenantPlan
+      detail: docs/TenantPlan/:name
+    permissions:
+      list: any
+      detail: any
+    in_sidebar: true
+    display_order: 55
+  ascii_icon: 🎫
+  display_label: Tenant Plans
+  docs: A TenantPlan maps one DNA tenant to its current Tier as GLOBAL
+    declarative data, so enforcement follows billing state without a redeploy.
+    dna-cloud's Stripe webhook writes it on subscribe/cancel; the MCP server
+    reads it via kernel.tenant_plan(tenant) when the token carries no explicit
+    plan claim — zero Stripe/billing code lives in the OSS SDK, which only reads
+    the assignment.

package/dist/extensions/cloud/kinds/tier.kind.yaml

@@ -0,0 +1,135 @@
+# Tier — DNA Cloud pricing-tier registry (record plane).
+# One doc per plan (free/pro/enterprise): hard caps (calls_per_day, rate_per_sec,
+# max_tenants) + which feature families it unlocks + price, as first-class GLOBAL
+# data so a limit change is a file edit, never a redeploy. NOT named `Plan` — that
+# alias belongs to the SDLC implementation-plan Kind; a pricing plan is a Tier.
+#
+# CONTRACT — never hardcode caps: the quota enforcer reads calls_per_day /
+# rate_per_sec / max_tenants from THIS registry via kernel.tier(id_or_alias); a
+# cap literal in code is a bug.
+#
+# Tiers live in the `_lib` scope (`tiers/<tier_id>.yaml`) — Tier is GLOBAL (base
+# only, no per-tenant override) and NOT inheritable; kernel.tier() queries `_lib`
+# directly regardless of the caller's scope.
+#
+# PARITY-CRITICAL package data: the byte-identical mirror lives at
+# packages/sdk-{py,ts}/{dna/extensions,src/extensions}/cloud/kinds/
+# tier.kind.yaml (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: tier
+spec:
+  target_api_version: github.com/ruinosus/dna/cloud/v1
+  target_kind: Tier
+  alias: cloud-tier
+  origin: github.com/ruinosus/dna/cloud
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: tiers
+  schema:
+    type: object
+    additionalProperties: false
+    required:
+    - tier_id
+    - display_name
+    properties:
+      tier_id:
+        type: string
+        description: Canonical tier id, e.g. free, pro, enterprise. The doc name
+          SHOULD equal the tier_id; kernel.tier() matches on this field first.
+      display_name:
+        type: string
+        description: Human-facing plan name, e.g. Free, Pro, Enterprise.
+      price_usd_month:
+        type: number
+        default: 0
+        description: Flat monthly price in USD (0 for the free tier).
+      calls_per_day:
+        type:
+        - integer
+        - 'null'
+        description: Daily call quota. Null = unlimited (enterprise). THE value
+          the quota enforcer reads — never hardcode it in code.
+      rate_per_sec:
+        type:
+        - integer
+        - 'null'
+        description: Per-second rate limit. Null = unmetered.
+      max_tenants:
+        type:
+        - integer
+        - 'null'
+        description: Number of tenants the plan allows. Null = unlimited.
+      feature_families:
+        type: array
+        items:
+          type: string
+        description: Tool families this tier unlocks, e.g.
+          [definitions, sdlc, memory, emit].
+      memory_mode:
+        type: string
+        enum:
+        - none
+        - read
+        - write
+        default: none
+        description: Memory access level granted by the tier — none, read, or
+          write.
+      overage_per_1k_usd:
+        type:
+        - number
+        - 'null'
+        description: USD charged per 1k calls above the daily quota. Null = no
+          overage (hard cap).
+      sla:
+        type: boolean
+        default: false
+        description: True when the tier includes a support/uptime SLA
+          (enterprise).
+      aliases:
+        type: array
+        items:
+          type: string
+        description: Alternate ids that resolve to this tier (legacy plan names).
+          kernel.tier() matches these on pass 2.
+      notes:
+        type:
+        - string
+        - 'null'
+        description: Free-form operator notes.
+  describe: '{display_name} (${price_usd_month}/mo)'
+  summary:
+    tier_id: ''
+    display_name: ''
+    price_usd_month: 0
+    calls_per_day: null
+  ui:
+    mode: govern
+    label:
+      en: Tiers
+      pt-BR: Planos
+    icon: 💳
+    description:
+      en: DNA Cloud pricing tiers (caps + feature families).
+      pt-BR: Planos do DNA Cloud (limites + famílias de features).
+    routes:
+      list: docs/Tier
+      detail: docs/Tier/:name
+    permissions:
+      list: any
+      detail: any
+    in_sidebar: true
+    display_order: 54
+  ascii_icon: 💳
+  display_label: Tiers
+  docs: A Tier declares one DNA Cloud plan's hard caps (calls/day, rate, tenants)
+    and which feature families it unlocks, as GLOBAL declarative data so changing
+    a limit is a file edit, not a redeploy. Resolve it via
+    kernel.tier(id_or_alias); the quota enforcer reads the caps from here and
+    never hardcodes them.