@aestheticfunction/dspack-gen 0.1.0

package/dist/adapters/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Generation adapter interface (ADR-9) — the thesis-bearing seam between the
+ * pipeline and model providers. Stateless: one attempt per call; the repair
+ * loop owns conversation state.
+ *
+ * Model identity is CONFIGURATION: adapters require an explicit model ID
+ * (config/env/CLI flag) and no default model name exists in this codebase —
+ * defaults are resolved at implementation/run time and recorded in config.
+ *
+ * Honesty note (S0 spike, docs/spike-structured-outputs.md): constrained
+ * decoding cannot be assumed to have been applied — Ollama's mlx engine
+ * silently ignores `format`. Adapters guarantee only that the result parses
+ * as JSON (AdapterOutputError otherwise); schema/vocabulary/governance
+ * conformance is judged by the surface gates S1/S2/S3 over the artifact.
+ */
+export interface GenerateMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface GenerateRequest {
+    system: string;
+    messages: GenerateMessage[];
+    /** The generation schema (constrained decoding / output schema). */
+    jsonSchema: Record<string, unknown>;
+    params?: {
+        /** Sent to providers that accept it (Ollama). Never sent to Anthropic (removed on current models). */
+        temperature?: number;
+        maxTokens?: number;
+    };
+}
+export interface GenerateResult {
+    /** The parsed JSON output — shape-checked by gates, not here. */
+    json: unknown;
+    /** The raw text the model produced. */
+    raw: string;
+    /** The model that actually served the request, as reported by the provider. */
+    model: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    /** Provider-specific timings/engine info, recorded verbatim in audit reports. */
+    meta?: Record<string, unknown>;
+}
+export interface GenerationAdapter {
+    /** Stable identity for audit reports, e.g. "ollama:<model-tag>" or "anthropic:<model-id>". */
+    readonly id: string;
+    generate(request: GenerateRequest): Promise<GenerateResult>;
+}
+/** The model produced output the adapter cannot hand to the pipeline (non-JSON, refusal, empty). */
+export declare class AdapterOutputError extends Error {
+    readonly adapterId: string;
+    readonly rawHead?: string | undefined;
+    constructor(adapterId: string, message: string, rawHead?: string | undefined);
+}
+/** Injectable for offline, deterministic tests. */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare function parseJsonOutput(adapterId: string, raw: string): unknown;
+/**
+ * Parse a `--model` flag: "ollama:<model-id>" or "anthropic:<model-id>".
+ * The model id itself may contain colons (ollama tags carry a size suffix).
+ */
+export declare function parseModelRef(ref: string): {
+    provider: "ollama" | "anthropic";
+    model: string;
+};

package/dist/adapters/types.js

@@ -0,0 +1,47 @@
+/**
+ * Generation adapter interface (ADR-9) — the thesis-bearing seam between the
+ * pipeline and model providers. Stateless: one attempt per call; the repair
+ * loop owns conversation state.
+ *
+ * Model identity is CONFIGURATION: adapters require an explicit model ID
+ * (config/env/CLI flag) and no default model name exists in this codebase —
+ * defaults are resolved at implementation/run time and recorded in config.
+ *
+ * Honesty note (S0 spike, docs/spike-structured-outputs.md): constrained
+ * decoding cannot be assumed to have been applied — Ollama's mlx engine
+ * silently ignores `format`. Adapters guarantee only that the result parses
+ * as JSON (AdapterOutputError otherwise); schema/vocabulary/governance
+ * conformance is judged by the surface gates S1/S2/S3 over the artifact.
+ */
+/** The model produced output the adapter cannot hand to the pipeline (non-JSON, refusal, empty). */
+export class AdapterOutputError extends Error {
+    adapterId;
+    rawHead;
+    constructor(adapterId, message, rawHead) {
+        super(`[${adapterId}] ${message}${rawHead ? ` (output head: ${JSON.stringify(rawHead.slice(0, 200))})` : ""}`);
+        this.adapterId = adapterId;
+        this.rawHead = rawHead;
+        this.name = "AdapterOutputError";
+    }
+}
+export function parseJsonOutput(adapterId, raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new AdapterOutputError(adapterId, "model output is not valid JSON — constrained decoding was not applied or failed (see docs/spike-structured-outputs.md: some engines silently ignore output schemas)", raw);
+    }
+}
+/**
+ * Parse a `--model` flag: "ollama:<model-id>" or "anthropic:<model-id>".
+ * The model id itself may contain colons (ollama tags carry a size suffix).
+ */
+export function parseModelRef(ref) {
+    const sep = ref.indexOf(":");
+    const provider = sep === -1 ? ref : ref.slice(0, sep);
+    const model = sep === -1 ? "" : ref.slice(sep + 1);
+    if ((provider !== "ollama" && provider !== "anthropic") || model === "") {
+        throw new Error(`invalid model reference '${ref}' (expected ollama:<model-id> or anthropic:<model-id>)`);
+    }
+    return { provider, model };
+}

package/dist/audit/report.d.ts

@@ -0,0 +1,84 @@
+import type { Contract } from "../core/contract.js";
+import type { Finding, GateReport } from "../core/lint/findings.js";
+export declare const REPORT_VERSION = "1";
+export type Outcome = "passed" | "failed-lint-exhausted" | "failed-gate" | "failed-adapter";
+/** Emitter gate result, keyed by the architecture-wide A-gate names. */
+export interface EmitterGate {
+    gate: "A1" | "A2" | "A3" | "J2" | "J3";
+    name: string;
+    pass: boolean;
+    errors?: string[];
+}
+export interface AttemptRecord {
+    index: number;
+    /** The generated dspack surface (absent when the adapter failed). */
+    surface?: unknown;
+    model?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    meta?: Record<string, unknown>;
+    adapterError?: string;
+    /** Surface gates S1/S2/S3, independently reported. */
+    gates?: GateReport[];
+    findings?: Finding[];
+}
+export interface EmittedValidation {
+    /** A2UI catalog version validated against (a2ui target only; absent for json-render). */
+    a2uiVersion?: string;
+    gates: EmitterGate[];
+}
+export interface AuditReportV1 {
+    reportVersion: typeof REPORT_VERSION;
+    createdAt: string;
+    request: {
+        prompt: string;
+        intent: string;
+        contract: {
+            name: string;
+            dspack: string;
+            sha256: string;
+        };
+    };
+    generation: {
+        adapterId: string;
+        schemaSha256: string;
+        maxRepairs: number;
+        ruleSteering: boolean;
+        /** ADR-7 repair template variant used for feedback (additive in v1; absent ⇒ "standard"). */
+        repairTemplate?: string;
+    };
+    attempts: AttemptRecord[];
+    /** Repair messages verbatim — rendered from the same findings objects above. */
+    repairMessages: string[];
+    outcome: Outcome;
+    emitted?: {
+        target: "a2ui" | "json-render";
+        /** Absent when the emitter refused the surface outright (see refusal). */
+        surfaceMessages?: unknown;
+        /** Emitter warnings — every synthesis/drop, nothing silent. */
+        warnings: Array<{
+            code: string;
+            message: string;
+        }>;
+        validations: EmittedValidation[];
+        /**
+         * The emitter's typed refusal message when a lint-clean surface could
+         * not be emitted at all (additive in v1) — the target-equivalent
+         * emitter-gate failure; validations is empty in that case.
+         */
+        refusal?: string;
+    };
+    timings: {
+        totalMs: number;
+    };
+}
+export declare function sha256(value: unknown): string;
+export declare function contractDigest(contract: Contract): {
+    name: string;
+    dspack: string;
+    sha256: string;
+};
+/** Human view of the JSON artifact — derived, never the source of truth. */
+export declare function renderMarkdown(report: AuditReportV1): string;

package/dist/audit/report.js

@@ -0,0 +1,62 @@
+/**
+ * Audit report v1 (ADR-8): a versioned, schema'd artifact from day one.
+ * JSON is the artifact (schemas/audit-report.v1.schema.json); the Markdown
+ * rendering is a derived view. Stability guarantee: additive-only within
+ * reportVersion "1" (docs/AUDIT.md).
+ */
+import { createHash } from "node:crypto";
+export const REPORT_VERSION = "1";
+export function sha256(value) {
+    return createHash("sha256").update(typeof value === "string" ? value : JSON.stringify(value)).digest("hex");
+}
+export function contractDigest(contract) {
+    return { name: contract.name, dspack: contract.dspack, sha256: sha256(contract) };
+}
+/** Human view of the JSON artifact — derived, never the source of truth. */
+export function renderMarkdown(report) {
+    const lines = [
+        `# Audit report (v${report.reportVersion})`,
+        "",
+        `- **Outcome:** ${report.outcome}`,
+        `- **Prompt:** ${report.request.prompt}`,
+        `- **Intent:** ${report.request.intent}`,
+        `- **Contract:** ${report.request.contract.name} (dspack ${report.request.contract.dspack}, sha256 ${report.request.contract.sha256.slice(0, 12)}…)`,
+        `- **Adapter:** ${report.generation.adapterId} (max repairs: ${report.generation.maxRepairs}, rule steering: ${report.generation.ruleSteering})`,
+        `- **Created:** ${report.createdAt} · **Duration:** ${report.timings.totalMs} ms`,
+    ];
+    report.attempts.forEach((attempt) => {
+        lines.push("", `## Attempt ${attempt.index + 1}`);
+        if (attempt.adapterError) {
+            lines.push(`- Adapter error: ${attempt.adapterError}`);
+            return;
+        }
+        if (attempt.model)
+            lines.push(`- Model: ${attempt.model}`);
+        for (const gate of attempt.gates ?? []) {
+            lines.push(`- gate ${gate.gate} ${gate.name}: **${gate.status}**`);
+        }
+        for (const finding of attempt.findings ?? []) {
+            lines.push(`  - ${finding.level} [${finding.requirement}] ${finding.ruleId} at ${finding.location.path} — ${finding.message}`);
+        }
+        const repair = report.repairMessages[attempt.index];
+        if (repair) {
+            lines.push("", "### Repair feedback sent", "", "```", repair, "```");
+        }
+    });
+    if (report.emitted) {
+        lines.push("", "## Emitted (A2UI)");
+        if (report.emitted.refusal) {
+            lines.push(`- **REFUSED by the emitter:** ${report.emitted.refusal}`);
+        }
+        for (const validation of report.emitted.validations) {
+            for (const gate of validation.gates) {
+                lines.push(`- [${validation.a2uiVersion ?? report.emitted.target}] gate ${gate.gate} ${gate.name}: **${gate.pass ? "PASS" : "FAIL"}**`);
+            }
+        }
+        for (const warning of report.emitted.warnings) {
+            lines.push(`- note ${warning.code}: ${warning.message}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * dspack-gen CLI.
+ *
+ *   dspack-gen context --dspack <contract.json> --intent <id> [--depth N] [--no-steering]
+ *   dspack-gen lint    --dspack <contract.json> --surface <file.dsurface.json>
+ *
+ * `context` prints the compiled generation context ({ system, schema, fewshot }).
+ * `lint` runs surface gates S1–S3: machine-readable JSON report on stdout,
+ * human rendering on stderr. Later PRs add `run` (the full pipeline).
+ *
+ * Exit codes (full table in README): 0 clean, 1 internal/usage error,
+ * 2 governance failure (any S-gate error), 3 emitter-gate failure,
+ * 4 unknown rule type.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { compileContext } from "./core/compiler.js";
+import { lintSurface, renderText, UnknownRuleTypeError } from "./core/lint/index.js";
+import { adapterFor, AdapterOutputError } from "./adapters/index.js";
+import { runPipeline } from "./run/orchestrator.js";
+import { renderMarkdown } from "./audit/report.js";
+function fail(message) {
+    console.error(`error: ${message}`);
+    process.exit(1);
+}
+const BOOLEAN_FLAGS = new Set(["no-steering"]);
+function parseFlags(argv) {
+    const flags = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token.startsWith("--"))
+            fail(`unexpected argument '${token}' (flags start with --)`);
+        const eq = token.indexOf("=");
+        if (eq !== -1) {
+            flags.set(token.slice(2, eq), token.slice(eq + 1));
+        }
+        else if (BOOLEAN_FLAGS.has(token.slice(2))) {
+            flags.set(token.slice(2), "true");
+        }
+        else {
+            const value = argv[++i];
+            if (value === undefined)
+                fail(`flag '${token}' is missing a value`);
+            flags.set(token.slice(2), value);
+        }
+    }
+    return flags;
+}
+function commandContext(flags) {
+    const contractPath = flags.get("dspack") ?? fail("--dspack <contract.json> is required");
+    const intent = flags.get("intent") ?? fail("--intent <id> is required");
+    const contract = JSON.parse(readFileSync(resolve(contractPath), "utf8"));
+    let context;
+    try {
+        context = compileContext(contract, intent, {
+            depth: flags.has("depth") ? Number(flags.get("depth")) : undefined,
+            omitRuleSteering: flags.get("no-steering") === "true",
+        });
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+    process.stdout.write(JSON.stringify(context, null, 2) + "\n");
+}
+function commandLint(flags) {
+    const contractPath = flags.get("dspack") ?? fail("--dspack <contract.json> is required");
+    const surfacePath = flags.get("surface") ?? fail("--surface <file.dsurface.json> is required");
+    const contract = JSON.parse(readFileSync(resolve(contractPath), "utf8"));
+    const surface = JSON.parse(readFileSync(resolve(surfacePath), "utf8"));
+    try {
+        const report = lintSurface(surface, contract);
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        process.stderr.write(renderText(report) + "\n");
+        process.exit(report.pass ? 0 : 2);
+    }
+    catch (e) {
+        if (e instanceof UnknownRuleTypeError) {
+            console.error(`error: ${e.message}`);
+            process.exit(4);
+        }
+        throw e;
+    }
+}
+function parseMaxRepairs(flags) {
+    if (!flags.has("max-repairs"))
+        return undefined;
+    const value = Number(flags.get("max-repairs"));
+    if (!Number.isInteger(value) || value < 0) {
+        fail(`--max-repairs must be a non-negative integer (got '${flags.get("max-repairs")}')`);
+    }
+    return value;
+}
+async function commandRun(flags) {
+    const contractPath = flags.get("dspack") ?? fail("--dspack <contract.json> is required");
+    const intent = flags.get("intent") ?? fail("--intent <id> is required");
+    const prompt = flags.get("prompt") ?? fail("--prompt <text> is required");
+    const modelRef = flags.get("model") ?? fail("--model ollama:<id>|anthropic:<id> is required");
+    const outDir = flags.get("out") ?? "out";
+    const contract = JSON.parse(readFileSync(resolve(contractPath), "utf8"));
+    let result;
+    try {
+        result = await runPipeline({
+            contract,
+            intent,
+            prompt,
+            adapter: adapterFor(modelRef),
+            maxRepairs: parseMaxRepairs(flags),
+            compile: {
+                depth: flags.has("depth") ? Number(flags.get("depth")) : undefined,
+                omitRuleSteering: flags.get("no-steering") === "true",
+            },
+        });
+    }
+    catch (e) {
+        if (e instanceof UnknownRuleTypeError) {
+            console.error(`error: ${e.message}`);
+            process.exit(4);
+        }
+        if (e instanceof AdapterOutputError) {
+            console.error(`error: ${e.message}`);
+            process.exit(1);
+        }
+        throw e;
+    }
+    mkdirSync(resolve(outDir), { recursive: true });
+    writeFileSync(join(resolve(outDir), "audit-report.json"), JSON.stringify(result.report, null, 2) + "\n");
+    writeFileSync(join(resolve(outDir), "audit-report.md"), renderMarkdown(result.report));
+    if (result.surfaceMessages) {
+        writeFileSync(join(resolve(outDir), "generated.surface.json"), JSON.stringify(result.surfaceMessages, null, 2) + "\n");
+    }
+    console.error(`outcome: ${result.report.outcome} (${result.report.attempts.length} attempt(s))`);
+    console.error(`audit report -> ${join(outDir, "audit-report.json")}`);
+    process.exit(result.exitCode);
+}
+const USAGE = `dspack-gen <command> [flags]
+
+Commands:
+  context --dspack <contract.json> --intent <id> [--depth N] [--no-steering]
+      Print the compiled generation context ({ system, schema, fewshot }).
+  lint --dspack <contract.json> --surface <file.dsurface.json>
+      Run surface gates S1-S3; JSON report on stdout, human rendering on stderr.
+  run --dspack <contract.json> --intent <id> --prompt <text> --model <ref> [--out <dir>] [--max-repairs N]
+      Full pipeline: generate -> lint -> repair -> emit -> audit report.
+      <ref> is ollama:<id> or anthropic:<id>.
+  serve --dspack <contract.json> [--port <n>]
+      Localhost NDJSON server streaming the pipeline.
+
+Exit codes: 0 clean, 1 usage/internal error, 2 governance failure,
+3 emitter-gate failure, 4 unknown rule type.`;
+function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+        console.log(USAGE);
+        process.exit(command === undefined ? 1 : 0);
+    }
+    const flags = parseFlags(rest);
+    if (command === "context")
+        return commandContext(flags);
+    if (command === "lint")
+        return commandLint(flags);
+    if (command === "run") {
+        void commandRun(flags);
+        return;
+    }
+    if (command === "serve") {
+        let port;
+        if (flags.has("port")) {
+            port = Number(flags.get("port"));
+            if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                fail(`--port must be an integer between 1 and 65535 (got '${flags.get("port")}')`);
+            }
+        }
+        void import("./serve.js").then(({ startServer }) => startServer({
+            contractPath: flags.get("dspack") ?? "fixtures/shadcn.v0_4.dspack.json",
+            port,
+        }));
+        return;
+    }
+    fail(`unknown command '${command ?? ""}' (available: context, lint, run, serve)`);
+}
+main();

package/dist/core/compiler.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Prompt/context compiler: dspack v0.3 contract × declared intent →
+ * { system, schema, fewshot }.
+ *
+ * - `system`: the compiled system prompt — vocabulary, governance rules
+ *   rendered as instructions with rationales, and design-intent guidance.
+ *   Deterministic (golden-file tested) and immutable across repair attempts
+ *   (ADR-7: the only delta between attempts is the repair feedback).
+ * - `schema`: the generation schema (see generation-schema.ts). Shape only,
+ *   never governance — the prompt's rules section is steering; the guarantee
+ *   is gate S3.
+ * - `fewshot`: user/assistant message pairs from the contract's examples for
+ *   the intent, verbatim (ADR-3: the surface format IS the generation format,
+ *   so exemplars are exactly in-distribution).
+ */
+import { type Contract, type RuleEntry } from "./contract.js";
+import { type GenerationSchemaOptions } from "./generation-schema.js";
+export interface FewshotMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface CompiledContext {
+    system: string;
+    schema: Record<string, unknown>;
+    fewshot: FewshotMessage[];
+}
+export interface CompileOptions extends GenerationSchemaOptions {
+    /**
+     * Omit the governance-rules section from the system prompt. The linter (S3)
+     * is unaffected — this only removes prompt steering. Used by demos/evals to
+     * observe first-attempt violation rates honestly.
+     */
+    omitRuleSteering?: boolean;
+}
+/** Rules that fire for an intent: universal rules plus intent-scoped ones. */
+export declare function applicableRules(contract: Contract, intentId: string): RuleEntry[];
+export declare function compileContext(contract: Contract, intentId: string, options?: CompileOptions): CompiledContext;
+/** One-sentence imperative rendering of a rule (the rationale is appended by the caller). */
+export declare function ruleInstruction(rule: RuleEntry, contract?: Contract): string;

package/dist/core/compiler.js

@@ -0,0 +1,142 @@
+/**
+ * Prompt/context compiler: dspack v0.3 contract × declared intent →
+ * { system, schema, fewshot }.
+ *
+ * - `system`: the compiled system prompt — vocabulary, governance rules
+ *   rendered as instructions with rationales, and design-intent guidance.
+ *   Deterministic (golden-file tested) and immutable across repair attempts
+ *   (ADR-7: the only delta between attempts is the repair feedback).
+ * - `schema`: the generation schema (see generation-schema.ts). Shape only,
+ *   never governance — the prompt's rules section is steering; the guarantee
+ *   is gate S3.
+ * - `fewshot`: user/assistant message pairs from the contract's examples for
+ *   the intent, verbatim (ADR-3: the surface format IS the generation format,
+ *   so exemplars are exactly in-distribution).
+ */
+import { categoryIndex, enumValues, getIntent, } from "./contract.js";
+import { buildGenerationSchema } from "./generation-schema.js";
+/** Rules that fire for an intent: universal rules plus intent-scoped ones. */
+export function applicableRules(contract, intentId) {
+    return (contract.rules ?? []).filter((rule) => !rule.appliesTo || rule.appliesTo.intents.includes(intentId));
+}
+export function compileContext(contract, intentId, options = {}) {
+    const intent = getIntent(contract, intentId);
+    const rules = applicableRules(contract, intentId);
+    const examples = (contract.examples ?? []).filter((e) => e.intent === intentId);
+    return {
+        system: renderSystemPrompt(contract, intent, options.omitRuleSteering ? [] : rules, options),
+        schema: buildGenerationSchema(contract, intentId, options),
+        fewshot: examples.flatMap((example) => fewshotPair(example)),
+    };
+}
+function fewshotPair(example) {
+    return [
+        { role: "user", content: example.prompt ?? example.description ?? example.id },
+        { role: "assistant", content: JSON.stringify(example.surface) },
+    ];
+}
+function renderSystemPrompt(contract, intent, rules, options) {
+    const lines = [
+        `You generate user interface surfaces for the "${contract.name}" design system. You must respond`,
+        "with a single JSON object conforming to the provided schema — a dspack surface document.",
+        "",
+        "## Component vocabulary",
+        "You may use only these components (with the listed props and allowed values):",
+    ];
+    for (const [id, component] of Object.entries(contract.components ?? {})) {
+        const props = Object.entries(component.props ?? {})
+            .map(([name, descriptor]) => {
+            const values = enumValues(descriptor);
+            return values ? `${name} ∈ {${values.map(String).join(", ")}}` : name;
+        })
+            .join("; ");
+        const subs = (component.composition?.subComponents ?? []).map((s) => s.id).join(", ");
+        let line = `- ${id} — ${component.description}`;
+        if (props)
+            line += ` Props: ${props}.`;
+        if (subs)
+            line += ` Sub-components (used as children): ${subs}.`;
+        lines.push(line);
+    }
+    if (rules.length > 0) {
+        lines.push("", `## Governance rules in effect (intent: ${intent.id})`, "These are hard requirements. Surfaces violating them will be rejected:");
+        rules.forEach((rule, i) => {
+            lines.push(`${i + 1}. [${rule.id} / ${rule.severity}] ${ruleInstruction(rule, contract)} Why: ${rule.rationale}`);
+        });
+    }
+    lines.push("", "## Design intent", `Intent "${intent.id}": ${intent.description}`);
+    for (const patternId of intent.relatedPatterns ?? []) {
+        const pattern = (contract.patterns ?? []).find((p) => p.id === patternId);
+        if (pattern?.guidance)
+            lines.push(`Related pattern "${pattern.name ?? pattern.id}": ${pattern.guidance}`);
+    }
+    lines.push("", "Output only the JSON object. No commentary.");
+    void options;
+    return lines.join("\n");
+}
+/** One-sentence imperative rendering of a rule (the rationale is appended by the caller). */
+export function ruleInstruction(rule, contract) {
+    switch (rule.type) {
+        case "component-choice": {
+            const r = rule;
+            const parts = [];
+            if (r.require?.length)
+                parts.push(`Use ${r.require.join(", ")} for this surface`);
+            if (r.forbid?.length)
+                parts.push(`${r.forbid.join(", ")} ${r.forbid.length === 1 ? "is" : "are"} forbidden`);
+            return `${parts.join("; ")}.`;
+        }
+        case "required-composition": {
+            const r = rule;
+            const needs = [];
+            if (r.requiredSubComponents?.length)
+                needs.push(r.requiredSubComponents.map((s) => s.id).join(" and "));
+            if (r.requiredProps?.length)
+                needs.push(r.requiredProps.map((p) => `${p.prop} set to one of ${p.oneOf.map(String).join("/")}`).join(" and "));
+            return `Every ${r.component} must contain ${needs.join(", plus ")}.`;
+        }
+        case "forbidden-composition": {
+            const r = rule;
+            const parts = [];
+            if (r.forbiddenDescendants?.length)
+                parts.push(`Never place ${r.forbiddenDescendants.join(" or ")} inside a ${r.component}`);
+            // Steering names the category AND its resolved member ids, so the
+            // model sees concrete vocabulary (mirrors the finding message).
+            const memberships = r.forbiddenCategories?.length && contract ? categoryIndex(contract) : undefined;
+            for (const category of r.forbiddenCategories ?? []) {
+                const members = memberships
+                    ? [...memberships].filter(([, cats]) => cats.includes(category)).map(([id]) => id)
+                    : [];
+                parts.push(`never place ${category}-category components${members.length ? ` (${members.join(", ")})` : ""} inside ${r.component}`);
+            }
+            if (r.forbiddenProps?.length)
+                parts.push(r.forbiddenProps
+                    .map((p) => `never set ${p.prop} to ${p.values.map(String).join("/")} on ${r.component}`)
+                    .join("; "));
+            return `${parts.join("; ")}.`;
+        }
+        case "required-props": {
+            const r = rule;
+            const scope = r.within ? `At least one ${r.component} inside each ${r.within}` : `Every ${r.component}`;
+            const needs = [];
+            if (r.requiredText) {
+                needs.push(r.textScope === "subtree"
+                    ? "contain non-empty text (its own `text` field or a descendant's)"
+                    : "carry its label as its own `text` field (never nested in a child component)");
+            }
+            for (const p of r.requiredProps ?? []) {
+                needs.push(p.oneOf ? `set ${p.prop} to one of ${p.oneOf.map(String).join("/")}` : `set ${p.prop} directly`);
+            }
+            // Schema-invalid but defensive: no constraints to phrase → generic steering,
+            // never a malformed "must ;" sentence (the linter still evaluates the rule).
+            if (needs.length === 0)
+                return `Follow rule ${rule.id}.`;
+            const existence = r.within ? `; every ${r.within} must contain a ${r.component}` : "";
+            return `${scope} must ${needs.join(", and ")}${existence}.`;
+        }
+        default:
+            // The linter hard-errors on unknown types (exit 4); the compiler simply
+            // does not render steering it cannot phrase.
+            return `Follow rule ${rule.id}.`;
+    }
+}