intentdna 1.9.0 → 1.9.3

package/dist/runtime/workspace-observation.js

@@ -0,0 +1,216 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants, realpathSync } from "node:fs";
+import { lstat, open, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+export class WorkspaceObservationError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "WorkspaceObservationError";
+        this.code = code;
+    }
+}
+export const DEFAULT_WORKSPACE_OBSERVATION_LIMITS = {
+    max_entries: 100_000,
+    max_bytes: 1_073_741_824,
+    max_depth: 64,
+    max_duration_ms: 30_000,
+};
+export const WORKSPACE_OBSERVATION_EXCLUDED_PATHS = [
+    ".dna/runtime",
+    ".dna/worktrees/runtime",
+];
+const GIT_EXCLUSION_PATHSPECS = [
+    ":(exclude).dna/runtime",
+    ":(exclude).dna/runtime/**",
+    ":(exclude).dna/worktrees/runtime",
+    ":(exclude).dna/worktrees/runtime/**",
+];
+function metadata(value) {
+    const record = value;
+    return {
+        dev: String(record.dev),
+        ino: String(record.ino),
+        mode: String(record.mode),
+        size: String(record.size),
+        mtime_ns: String(record.mtimeNs),
+        ctime_ns: String(record.ctimeNs),
+    };
+}
+function sameMetadata(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function canonicalNameOrder(left, right) {
+    return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+function isExcluded(relativePath) {
+    return relativePath === ".git" || WORKSPACE_OBSERVATION_EXCLUDED_PATHS.some((excluded) => (relativePath === excluded || relativePath.startsWith(`${excluded}/`)));
+}
+function normalizedRelative(root, path) {
+    return relative(root, path).split(sep).join("/") || ".";
+}
+function git(cwd, args) {
+    const result = spawnSync("git", [...args], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+function gitSnapshot(root) {
+    const top = git(root, ["rev-parse", "--show-toplevel"]);
+    if (top.status !== 0)
+        return null;
+    const common = git(root, ["rev-parse", "--git-common-dir"]);
+    const head = git(root, ["rev-parse", "--verify", "HEAD"]);
+    const branch = git(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    const status = git(root, [
+        "status", "--porcelain=v2", "--untracked-files=all", "--",
+        ".", ...GIT_EXCLUSION_PATHSPECS,
+    ]);
+    const localConfig = git(root, ["config", "--local", "--null", "--list"]);
+    if (common.status !== 0 || head.status !== 0 || status.status !== 0 || localConfig.status !== 0) {
+        throw new WorkspaceObservationError("verification_failed", status.stderr.trim() || head.stderr.trim() || common.stderr.trim()
+            || localConfig.stderr.trim() || "Git workspace inspection failed");
+    }
+    const commonPath = common.stdout.trim();
+    const identityPath = isAbsolute(commonPath) ? commonPath : resolve(root, commonPath);
+    return {
+        repository_identity_digest: `sha256:${createHash("sha256")
+            .update(realpathSyncForSnapshot(identityPath), "utf8")
+            .digest("hex")}`,
+        head: head.stdout.trim(),
+        symbolic_branch: branch.status === 0 ? branch.stdout.trim() : null,
+        porcelain_v2_digest: `sha256:${createHash("sha256").update(status.stdout, "utf8").digest("hex")}`,
+        local_config_digest: `sha256:${createHash("sha256").update(localConfig.stdout, "utf8").digest("hex")}`,
+    };
+}
+function realpathSyncForSnapshot(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        throw new WorkspaceObservationError("verification_failed", `cannot resolve Git repository identity: ${path}`);
+    }
+}
+function validateLimits(input) {
+    const limits = { ...DEFAULT_WORKSPACE_OBSERVATION_LIMITS, ...input };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new WorkspaceObservationError("verification_failed", `${name} must be a non-negative safe integer`);
+        }
+    }
+    return limits;
+}
+export function workspaceObservationPolicy(limits) {
+    return {
+        schema_version: "intentdna.workspace_observation_policy.v1",
+        limits: validateLimits(limits),
+        excluded_relative_paths: WORKSPACE_OBSERVATION_EXCLUDED_PATHS,
+        git_observation: "head_branch_status_local_config",
+    };
+}
+export async function observeWorkspace(request) {
+    const requestedRoot = resolve(request.workspace_root);
+    const requestedStatus = await lstat(requestedRoot, { bigint: true });
+    if (requestedStatus.isSymbolicLink()) {
+        throw new WorkspaceObservationError("verification_failed", "workspace_root must not be a symlink");
+    }
+    const root = await realpath(requestedRoot);
+    const rootStatus = await lstat(root, { bigint: true });
+    if (!rootStatus.isDirectory() || rootStatus.isSymbolicLink()) {
+        throw new WorkspaceObservationError("verification_failed", "workspace_root must be a real directory");
+    }
+    const limits = validateLimits(request.limits);
+    const now = request.now_ms ?? Date.now;
+    const startedAt = now();
+    const digest = createHash("sha256");
+    let entries = 0;
+    let bytes = 0;
+    const enforce = (depth) => {
+        if (depth > limits.max_depth)
+            throw new WorkspaceObservationError("observation_limit_exceeded", "workspace depth limit exceeded");
+        if (entries > limits.max_entries)
+            throw new WorkspaceObservationError("observation_limit_exceeded", "workspace entry limit exceeded");
+        if (bytes > limits.max_bytes)
+            throw new WorkspaceObservationError("observation_limit_exceeded", "workspace byte limit exceeded");
+        if (now() - startedAt > limits.max_duration_ms)
+            throw new WorkspaceObservationError("observation_limit_exceeded", "workspace duration limit exceeded");
+    };
+    const updateRecord = (kind, relativePath, meta) => {
+        digest.update(`${kind}\0${Buffer.byteLength(relativePath)}\0${relativePath}\0${JSON.stringify(meta)}\0`);
+    };
+    const visit = async (absolutePath, relativePath, depth) => {
+        enforce(depth);
+        const beforeStatus = await lstat(absolutePath, { bigint: true });
+        if (beforeStatus.isSymbolicLink()) {
+            throw new WorkspaceObservationError("verification_failed", `symlink is not allowed: ${relativePath}`);
+        }
+        entries += 1;
+        enforce(depth);
+        const before = metadata(beforeStatus);
+        if (beforeStatus.isDirectory()) {
+            updateRecord("directory", relativePath, before);
+            const names = (await readdir(absolutePath)).sort(canonicalNameOrder);
+            await request.hooks?.after_directory_read?.(relativePath);
+            for (const name of names) {
+                const childRelative = relativePath === "." ? name : `${relativePath}/${name}`;
+                if (isExcluded(childRelative))
+                    continue;
+                await visit(join(absolutePath, name), childRelative, depth + 1);
+            }
+            const after = metadata(await stat(absolutePath, { bigint: true }));
+            if (!sameMetadata(before, after)) {
+                throw new WorkspaceObservationError("source_drift", `directory changed while observing: ${relativePath}`);
+            }
+            return;
+        }
+        if (!beforeStatus.isFile()) {
+            throw new WorkspaceObservationError("verification_failed", `special file is not allowed: ${relativePath}`);
+        }
+        // Node does not expose openat(2), so same-user namespace replacement cannot be
+        // eliminated completely. O_NOFOLLOW plus descriptor/path revalidation closes
+        // the practical symlink and replacement windows without native code.
+        const handle = await open(absolutePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const descriptorBefore = metadata(await handle.stat({ bigint: true }));
+            if (!sameMetadata(before, descriptorBefore)) {
+                throw new WorkspaceObservationError("source_drift", `file changed before read: ${relativePath}`);
+            }
+            updateRecord("file", relativePath, before);
+            const stream = handle.createReadStream({ autoClose: false });
+            for await (const chunk of stream) {
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                bytes += buffer.length;
+                enforce(depth);
+                digest.update(buffer);
+            }
+            digest.update("\0");
+            const descriptorAfter = metadata(await handle.stat({ bigint: true }));
+            const pathAfter = await lstat(absolutePath, { bigint: true });
+            if (pathAfter.isSymbolicLink() || !sameMetadata(before, descriptorAfter) || !sameMetadata(before, metadata(pathAfter))) {
+                throw new WorkspaceObservationError("source_drift", `file changed while observing: ${relativePath}`);
+            }
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    const gitBefore = gitSnapshot(root);
+    await visit(root, ".", 0);
+    const gitAfter = gitSnapshot(root);
+    if (JSON.stringify(gitBefore) !== JSON.stringify(gitAfter)) {
+        throw new WorkspaceObservationError("source_drift", "Git workspace state changed while observing");
+    }
+    digest.update(`git\0${JSON.stringify(gitAfter)}\0`);
+    return {
+        schema_version: "intentdna.workspace_observation.v2",
+        observed_digest: `sha256:${digest.digest("hex")}`,
+        entry_count: entries,
+        byte_count: bytes,
+        excluded_relative_paths: WORKSPACE_OBSERVATION_EXCLUDED_PATHS,
+        git: gitAfter,
+    };
+}

package/dist/schema/controller-registry.d.ts

@@ -16,13 +16,6 @@ export declare const CONTROLLER_KIND_REGISTRY: readonly [{
     readonly requiredRoleKeys: readonly ["analyzer", "analysis_reviewer", "surgeon", "fix_reviewer", "test_runner"];
     readonly diagnosisRoleKeys: readonly ["analyzer", "analysis_reviewer"];
     readonly fixRoleKeys: readonly ["surgeon", "fix_reviewer", "test_runner"];
-}, {
-    readonly kind: "flutter_rewrite_fix_loop";
-    readonly label: "Flutter rewrite fix loop";
-    readonly supportsSkillGeneration: true;
-    readonly requiredRoleKeys: readonly ["analyzer", "analysis_reviewer", "surgeon", "fix_reviewer", "test_runner"];
-    readonly diagnosisRoleKeys: readonly ["analyzer", "analysis_reviewer"];
-    readonly fixRoleKeys: readonly ["surgeon", "fix_reviewer", "test_runner"];
 }, {
     readonly kind: "sequential";
     readonly label: "Sequential workflow gate";

package/dist/schema/controller-registry.js

@@ -14,14 +14,6 @@ export const CONTROLLER_KIND_REGISTRY = [
         diagnosisRoleKeys: ["analyzer", "analysis_reviewer"],
         fixRoleKeys: ["surgeon", "fix_reviewer", "test_runner"],
     },
-    {
-        kind: "flutter_rewrite_fix_loop",
-        label: "Flutter rewrite fix loop",
-        supportsSkillGeneration: true,
-        requiredRoleKeys: CONTROLLER_ROLE_KEYS,
-        diagnosisRoleKeys: ["analyzer", "analysis_reviewer"],
-        fixRoleKeys: ["surgeon", "fix_reviewer", "test_runner"],
-    },
     {
         kind: "sequential",
         label: "Sequential workflow gate",

package/dist/schema/types.d.ts

@@ -104,6 +104,7 @@ export interface HandoffArtifact {
     path?: string;
     name?: string;
     artifact_id?: string;
+    schema_ref?: string;
     from?: string;
     required?: boolean;
     description: string;
@@ -189,6 +190,20 @@ export interface CompletionCheck {
     command_success?: string;
     evaluator_result?: EvaluatorResultCompletion;
 }
+export interface CanonicalRuntimeStepDef {
+    /** Explicit consumed artifact ids whose authored paths become immutable handoff paths. */
+    prompt_handoff_bindings?: string[];
+    /** Canonical-only producer step ids keyed by consumed artifact id. */
+    handoff_sources?: Record<string, string>;
+    /** Require the execution surface to prove an independent caller for submission. */
+    require_attested_independent_submit?: boolean;
+    /** Canonical-only completion checks; legacy Skill projection keeps `completion`. */
+    completion?: CompletionCheck[];
+    /** Canonical-only structured/reference outputs; legacy Skill projection is unchanged. */
+    outputs?: HandoffArtifact[];
+    /** Canonical-only output protocol clarification appended to the worker prompt. */
+    prompt_suffix?: string;
+}
 /** Single step in a workflow */
 export interface WorkflowStepDef {
     id: string;
@@ -199,6 +214,7 @@ export interface WorkflowStepDef {
     run_if?: string;
     prompt?: string;
     completion?: CompletionCheck[];
+    canonical_runtime?: CanonicalRuntimeStepDef;
     checkpoints?: StepCheckpoint[];
     handoff?: StepHandoff;
     isolation?: WorkflowIsolation;
@@ -227,15 +243,66 @@ export interface WorkflowDef {
     default_isolation?: WorkflowIsolation;
     merge_strategy?: WorkflowMergeStrategy;
 }
-export type ControllerKind = "fix_loop" | "flutter_rewrite_fix_loop" | "sequential";
-export interface ControllerPolicyDef {
-    diagnosis_reuse_criteria?: string[];
-    progress_provenance_checks?: string[];
-    progress_provenance_failure?: string;
-    verdict_branches?: string[];
-    verdict_mapping?: string[];
-    stop_report?: string[];
-    constraints?: string[];
+export type ControllerKind = "fix_loop" | "sequential";
+export declare const CONTROLLER_RUNTIME_PROGRAM_SCHEMA_VERSION: "intentdna.controller_program.v1";
+export interface ControllerRuntimeDecisionDef {
+    step_id: string;
+    output_name: string;
+    schema_ref: string;
+    json_pointer: string;
+}
+export interface ControllerRuntimeReuseDef {
+    mode_input: string;
+    legacy: {
+        diagnosis_spec_reference_input: string;
+        diagnosis_spec_digest_input: string;
+        diagnosis_contract_reference_input: string;
+        diagnosis_contract_digest_input: string;
+    };
+    canonical: {
+        source_plan_input: string;
+        diagnosis_result_input: string;
+        review_result_input: string;
+        approval_reuse: {
+            enabled: boolean;
+            policy_id: string;
+            require_exact_artifact_ids: true;
+            require_exact_artifact_digests: true;
+        };
+    };
+    outputs: {
+        diagnosis_spec: string;
+        diagnosis_contract: string;
+        diagnosis_review: string;
+        diagnosis_review_verdict: string;
+    };
+}
+/**
+ * Canonical-only controller program. Runtime and drivers consume only the
+ * compiled ExecutableRunPlan; legacy kind/policy prose has no execution meaning.
+ */
+export interface ControllerRuntimeProgramDef {
+    schema_version: typeof CONTROLLER_RUNTIME_PROGRAM_SCHEMA_VERSION;
+    diagnosis: {
+        analyzer_step_id: string;
+        reviewer_step_id: string;
+        decision: ControllerRuntimeDecisionDef;
+        approved_value: string;
+        request_changes_value: string;
+    };
+    fix: {
+        surgeon_step_id: string;
+        reviewer_step_id: string;
+        verifier_step_id: string;
+        decision: ControllerRuntimeDecisionDef;
+        pass_value: string;
+        continue_value: string;
+        request_changes_value: string;
+        blocked_value: string;
+        diagnosis_contract_invalid_value: string;
+        provenance_invalid_value: string;
+    };
+    reuse?: ControllerRuntimeReuseDef;
 }
 export interface ControllerDef {
     name: string;
@@ -251,7 +318,7 @@ export interface ControllerDef {
     review_artifact_path?: string;
     roles: Record<string, string>;
     stop_format: "configured_stop_report" | "zh_three_part";
-    policy?: ControllerPolicyDef;
+    runtime_program?: ControllerRuntimeProgramDef;
 }
 /** Parallel block syntax sugar — expanded by compiler into steps with depends_on */
 export interface ParallelBlockDef {
@@ -328,7 +395,10 @@ export interface CompiledProvenanceManifest {
 export interface VariableDef {
     description: string;
     default: string;
+    runtime_type?: VariableRuntimeType;
 }
+export declare const VARIABLE_RUNTIME_TYPE_VALUES: readonly ["trusted_verifier_command"];
+export type VariableRuntimeType = typeof VARIABLE_RUNTIME_TYPE_VALUES[number];
 export interface DNAMetadata {
     created: string;
     updated: string;
@@ -580,6 +650,10 @@ export interface WorkflowStep {
     max_handoffs?: number;
     on_handoff_exhausted?: "skip" | "stop";
     blocked_items_path?: string;
+    /** Canonical compiler-only path substitutions derived from explicit handoff bindings. */
+    canonical_handoff_path_bindings?: Readonly<Record<string, string>>;
+    /** Canonical compiler-only independent submission requirement. */
+    canonical_requires_attested_independent_submit?: boolean;
 }
 /** A group of steps that can execute in parallel */
 export interface ParallelGroup {

package/dist/schema/types.js

@@ -17,3 +17,5 @@ export const WORKFLOW_ISOLATION_VALUES = ["none", "worktree", "auto"];
 export const WORKFLOW_STEP_FAILURE_VALUES = ["retry_with_feedback", "handoff", "skip"];
 export const WORKFLOW_HANDOFF_EXHAUSTED_VALUES = ["skip", "stop"];
 export const WORKFLOW_MERGE_STRATEGY_VALUES = ["escalate"];
+export const CONTROLLER_RUNTIME_PROGRAM_SCHEMA_VERSION = "intentdna.controller_program.v1";
+export const VARIABLE_RUNTIME_TYPE_VALUES = ["trusted_verifier_command"];

package/dist/schema/validate.js

@@ -8,7 +8,7 @@
  *   - No circular inheritance
  */
 import { isAbsolute } from "node:path";
-import { CHECKPOINT_ACTION_VALUES, HANDOFF_TYPE_VALUES, RETRY_BACKOFF_VALUES, TRANSITION_CONDITION_VALUES, WORKFLOW_HANDOFF_EXHAUSTED_VALUES, WORKFLOW_ISOLATION_VALUES, WORKFLOW_MERGE_STRATEGY_VALUES, WORKFLOW_STEP_FAILURE_VALUES, } from "./types.js";
+import { CHECKPOINT_ACTION_VALUES, HANDOFF_TYPE_VALUES, RETRY_BACKOFF_VALUES, TRANSITION_CONDITION_VALUES, WORKFLOW_HANDOFF_EXHAUSTED_VALUES, WORKFLOW_ISOLATION_VALUES, WORKFLOW_MERGE_STRATEGY_VALUES, WORKFLOW_STEP_FAILURE_VALUES, VARIABLE_RUNTIME_TYPE_VALUES, } from "./types.js";
 import { validateController } from "./validators/controllers.js";
 const SAFE_GENERATED_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
 const SAFE_GENERATED_DISPLAY_NAME = /^[A-Za-z0-9][A-Za-z0-9 _-]*$/;
@@ -620,6 +620,131 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
                 }
             }
         }
+        if (step.canonical_runtime !== undefined) {
+            const runtime = step.canonical_runtime;
+            if (typeof runtime !== "object" || runtime === null || Array.isArray(runtime)) {
+                errors.push({ path: `${stepPath}.canonical_runtime`, message: "canonical_runtime must be an object" });
+            }
+            else {
+                if (runtime.prompt_handoff_bindings !== undefined) {
+                    if (!Array.isArray(runtime.prompt_handoff_bindings) || runtime.prompt_handoff_bindings.length === 0) {
+                        errors.push({
+                            path: `${stepPath}.canonical_runtime.prompt_handoff_bindings`,
+                            message: "prompt_handoff_bindings must be a non-empty array",
+                        });
+                    }
+                    else {
+                        const seenBindings = new Set();
+                        for (let j = 0; j < runtime.prompt_handoff_bindings.length; j++) {
+                            const binding = runtime.prompt_handoff_bindings[j];
+                            if (typeof binding !== "string" || !isSafeGeneratedIdentifier(binding)) {
+                                errors.push({
+                                    path: `${stepPath}.canonical_runtime.prompt_handoff_bindings[${j}]`,
+                                    message: "binding id must contain only letters, digits, underscores, and hyphens",
+                                });
+                            }
+                            else if (seenBindings.has(binding)) {
+                                errors.push({
+                                    path: `${stepPath}.canonical_runtime.prompt_handoff_bindings[${j}]`,
+                                    message: `duplicate binding id '${binding}'`,
+                                });
+                            }
+                            else {
+                                seenBindings.add(binding);
+                            }
+                        }
+                    }
+                }
+                if (runtime.handoff_sources !== undefined) {
+                    if (typeof runtime.handoff_sources !== "object"
+                        || runtime.handoff_sources === null
+                        || Array.isArray(runtime.handoff_sources)
+                        || Object.keys(runtime.handoff_sources).length === 0) {
+                        errors.push({
+                            path: `${stepPath}.canonical_runtime.handoff_sources`,
+                            message: "handoff_sources must be a non-empty object",
+                        });
+                    }
+                    else {
+                        for (const [artifactId, sourceStepId] of Object.entries(runtime.handoff_sources)) {
+                            if (!isSafeGeneratedIdentifier(artifactId)) {
+                                errors.push({
+                                    path: `${stepPath}.canonical_runtime.handoff_sources.${artifactId}`,
+                                    message: "artifact id must contain only letters, digits, underscores, and hyphens",
+                                });
+                            }
+                            if (typeof sourceStepId !== "string" || !isSafeGeneratedIdentifier(sourceStepId)) {
+                                errors.push({
+                                    path: `${stepPath}.canonical_runtime.handoff_sources.${artifactId}`,
+                                    message: "source step id must contain only letters, digits, underscores, and hyphens",
+                                });
+                            }
+                        }
+                    }
+                }
+                if (runtime.require_attested_independent_submit !== undefined
+                    && typeof runtime.require_attested_independent_submit !== "boolean") {
+                    errors.push({
+                        path: `${stepPath}.canonical_runtime.require_attested_independent_submit`,
+                        message: "require_attested_independent_submit must be a boolean",
+                    });
+                }
+                if (runtime.completion !== undefined) {
+                    if (!Array.isArray(runtime.completion) || runtime.completion.length === 0) {
+                        errors.push({
+                            path: `${stepPath}.canonical_runtime.completion`,
+                            message: "canonical completion must be a non-empty array",
+                        });
+                    }
+                    else {
+                        for (let j = 0; j < runtime.completion.length; j++) {
+                            errors.push(...validateCompletionCheck(runtime.completion[j], `${stepPath}.canonical_runtime.completion[${j}]`));
+                        }
+                    }
+                }
+                if (runtime.outputs !== undefined) {
+                    if (!Array.isArray(runtime.outputs) || runtime.outputs.length === 0) {
+                        errors.push({
+                            path: `${stepPath}.canonical_runtime.outputs`,
+                            message: "canonical outputs must be a non-empty array",
+                        });
+                    }
+                    else {
+                        const outputIds = new Set();
+                        for (let j = 0; j < runtime.outputs.length; j++) {
+                            const artifact = runtime.outputs[j];
+                            const artifactPath = `${stepPath}.canonical_runtime.outputs[${j}]`;
+                            if (!HANDOFF_TYPE_VALUES.includes(artifact.type)) {
+                                errors.push({ path: `${artifactPath}.type`, message: `must be one of: ${HANDOFF_TYPE_VALUES.join(", ")}` });
+                            }
+                            if (!artifact.description) {
+                                errors.push({ path: `${artifactPath}.description`, message: "canonical output requires 'description'" });
+                            }
+                            const identity = artifact.artifact_id ?? artifact.name ?? artifact.path;
+                            if (!identity) {
+                                errors.push({ path: artifactPath, message: "canonical output must define path, name, or artifact_id" });
+                            }
+                            else if (outputIds.has(identity)) {
+                                errors.push({ path: artifactPath, message: `duplicate canonical output '${identity}'` });
+                            }
+                            else {
+                                outputIds.add(identity);
+                            }
+                            if (artifact.type === "state" && (typeof artifact.schema_ref !== "string" || artifact.schema_ref.trim() === "")) {
+                                errors.push({ path: `${artifactPath}.schema_ref`, message: "structured state output requires schema_ref" });
+                            }
+                        }
+                    }
+                }
+                if (runtime.prompt_suffix !== undefined
+                    && (typeof runtime.prompt_suffix !== "string" || runtime.prompt_suffix.trim() === "")) {
+                    errors.push({
+                        path: `${stepPath}.canonical_runtime.prompt_suffix`,
+                        message: "prompt_suffix must be a non-empty string",
+                    });
+                }
+            }
+        }
         for (const direction of ["consumes", "produces"]) {
             const artifacts = step.handoff?.[direction] ?? [];
             for (let j = 0; j < artifacts.length; j++) {
@@ -631,6 +756,9 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
                 if (!artifact.description) {
                     errors.push({ path: `${artifactPath}.description`, message: "handoff artifact requires 'description'" });
                 }
+                if (artifact.schema_ref !== undefined && (typeof artifact.schema_ref !== "string" || artifact.schema_ref.trim() === "")) {
+                    errors.push({ path: `${artifactPath}.schema_ref`, message: "schema_ref must be a non-empty string" });
+                }
                 if (artifact.required !== false && artifact.type !== "git_commit" && !artifact.path && !artifact.name && !artifact.artifact_id) {
                     errors.push({ path: artifactPath, message: "required handoff artifacts must define path, name, or artifact_id" });
                 }
@@ -805,6 +933,28 @@ export function validateDNA(dna) {
     for (const [name, role] of Object.entries(dna.roles ?? {})) {
         errors.push(...validateRole(name, role, geneNames));
     }
+    for (const [name, variable] of Object.entries(dna.variables ?? {})) {
+        if (typeof variable === "string")
+            continue;
+        const path = `variables.${name}`;
+        if (variable === null || typeof variable !== "object" || Array.isArray(variable)) {
+            errors.push({ path, message: "must be a string or variable definition" });
+            continue;
+        }
+        if (typeof variable.description !== "string" || !variable.description.trim()) {
+            errors.push({ path: `${path}.description`, message: "must be a non-empty string" });
+        }
+        if (typeof variable.default !== "string") {
+            errors.push({ path: `${path}.default`, message: "must be a string" });
+        }
+        if (variable.runtime_type !== undefined
+            && !VARIABLE_RUNTIME_TYPE_VALUES.includes(variable.runtime_type)) {
+            errors.push({
+                path: `${path}.runtime_type`,
+                message: `must be one of: ${VARIABLE_RUNTIME_TYPE_VALUES.join(", ")}`,
+            });
+        }
+    }
     // Validate workflow / workflows (mutually exclusive)
     if (dna.workflow !== undefined && dna.workflows !== undefined) {
         errors.push({

package/dist/schema/validators/controllers.d.ts

@@ -1,3 +1,3 @@
-import type { ControllerDef, WorkflowDef } from "../types.js";
+import { type ControllerDef, type WorkflowDef } from "../types.js";
 import type { ValidationError } from "../validate.js";
 export declare function validateController(controller: ControllerDef, roleNames: Set<string>, workflows: Record<string, WorkflowDef>, path: string): ValidationError[];