@aestheticfunction/dspack-gen 0.1.0

package/dist/run/orchestrator.js

@@ -0,0 +1,191 @@
+/**
+ * The pipeline orchestrator: generate → surface gates S1–S3 → bounded repair
+ * (≤ maxRepairs, default 2; ADR-7) → emit via the pinned A2UI emitter →
+ * emitter gates A1–A3 → audit report v1.
+ *
+ * Failure exits are first-class artifacts, never silent: every outcome —
+ * passed, failed-lint-exhausted (exit 2), failed-gate (exit 3),
+ * failed-adapter (exit 1) — produces a complete audit report. The system
+ * prompt is immutable across attempts; the only delta between attempts is
+ * the model's own output plus the rendered repair feedback.
+ */
+import { buildCatalogModel, emitJsonRenderSpec, EmitJsonRenderError, emitSurface, EmitSurfaceError, transform, validateSpecAgainstModel, } from "@aestheticfunction/dspack-emit";
+import { applicableRules, compileContext } from "../core/compiler.js";
+import { lintSurface } from "../core/lint/index.js";
+import { AdapterOutputError } from "../adapters/types.js";
+import { renderRepairMessage } from "../repair/render.js";
+import { contractDigest, sha256, REPORT_VERSION, } from "../audit/report.js";
+/** Map the emitter's ajv gate names onto the architecture-wide A1/A2/A3. */
+const A_GATE = {
+    "schema-compile + no-external-ref": "A1",
+    "catalog-shape": "A2",
+    instance: "A3",
+};
+export async function runPipeline(options) {
+    const { contract, intent, prompt, adapter } = options;
+    const maxRepairs = options.maxRepairs ?? 2;
+    const repairTemplate = options.repairTemplate ?? "standard";
+    const now = options.now ?? (() => new Date());
+    const startedAt = now();
+    const context = compileContext(contract, intent, options.compile);
+    const conversation = [...context.fewshot, { role: "user", content: prompt }];
+    // Purely observational, enforced: a throwing hook (e.g. a stream write
+    // after the client disconnected) must never abort the pipeline or change
+    // its outcome — the audit report is the artifact, events are a view.
+    const emit = (event) => {
+        try {
+            options.onEvent?.(event);
+        }
+        catch {
+            /* observational — swallowed by contract */
+        }
+    };
+    emit({
+        type: "start",
+        intent,
+        prompt,
+        adapterId: adapter.id,
+        ruleIds: applicableRules(contract, intent).map((rule) => rule.id),
+    });
+    const attempts = [];
+    const repairMessages = [];
+    const finalize = (outcome, exitCode, extra = {}, emitted) => ({
+        report: {
+            reportVersion: REPORT_VERSION,
+            createdAt: startedAt.toISOString(),
+            request: { prompt, intent, contract: contractDigest(contract) },
+            generation: {
+                adapterId: adapter.id,
+                schemaSha256: sha256(context.schema),
+                maxRepairs,
+                ruleSteering: !options.compile?.omitRuleSteering,
+                repairTemplate,
+            },
+            attempts,
+            repairMessages,
+            outcome,
+            ...(emitted ? { emitted } : {}),
+            timings: { totalMs: now().getTime() - startedAt.getTime() },
+        },
+        exitCode,
+        ...extra,
+    });
+    for (let index = 0; index <= maxRepairs; index++) {
+        let generated;
+        try {
+            // Snapshot per attempt: adapters may hold the request beyond the call.
+            generated = await adapter.generate({ system: context.system, messages: [...conversation], jsonSchema: context.schema });
+        }
+        catch (error) {
+            if (error instanceof AdapterOutputError) {
+                attempts.push({ index, adapterError: error.message });
+                const failed = finalize("failed-adapter", 1);
+                emit({ type: "done", outcome: failed.report.outcome, exitCode: failed.exitCode, report: failed.report });
+                return failed;
+            }
+            throw error;
+        }
+        // Surface gates S1–S3 over the artifact (UnknownRuleTypeError propagates: CLI exit 4).
+        const lint = lintSurface(generated.json, contract);
+        attempts.push({
+            index,
+            surface: generated.json,
+            model: generated.model,
+            usage: generated.usage,
+            meta: generated.meta,
+            gates: lint.gates,
+            findings: lint.findings,
+        });
+        emit({ type: "attempt", index, model: generated.model, surface: generated.json, gates: lint.gates, findings: lint.findings });
+        if (lint.pass) {
+            const surface = generated.json;
+            const doc = contract;
+            if (options.emitTarget === "json-render") {
+                // Second-emitter path (PR-21): same refusal semantics as a2ui — a
+                // typed emit error is the gate-failure class, never a crash.
+                try {
+                    const model = buildCatalogModel(doc, {});
+                    const { spec } = emitJsonRenderSpec(surface, doc, {});
+                    const findings = validateSpecAgainstModel(spec, model);
+                    const gates = [
+                        { gate: "J2", name: "emission accepted", pass: true },
+                        {
+                            gate: "J3",
+                            name: "instance validates against the generated catalog model",
+                            pass: findings.length === 0,
+                            ...(findings.length ? { errors: findings.map((f) => f.message) } : {}),
+                        },
+                    ];
+                    const pass = gates.every((g) => g.pass);
+                    const emitted = { target: "json-render", spec, warnings: [], validations: [{ gates }] };
+                    emit({ type: "emitted", validations: [{ gates }], warnings: [] });
+                    const result = pass ? finalize("passed", 0, { surface }, emitted) : finalize("failed-gate", 3, {}, emitted);
+                    emit({ type: "done", outcome: result.report.outcome, exitCode: result.exitCode, report: result.report });
+                    return result;
+                }
+                catch (error) {
+                    if (error instanceof EmitJsonRenderError) {
+                        const emitted = { target: "json-render", refusal: error.message, warnings: [], validations: [] };
+                        emit({ type: "emitted", validations: [], warnings: [] });
+                        const result = finalize("failed-gate", 3, {}, emitted);
+                        emit({ type: "done", outcome: result.report.outcome, exitCode: result.exitCode, report: result.report });
+                        return result;
+                    }
+                    throw error;
+                }
+            }
+            // The emitter can REFUSE a lint-clean surface outright (typed
+            // EmitSurfaceError — e.g. a sub-component outside its compound parent:
+            // in-vocabulary for S2, ungoverned by S3, unprojectable by the
+            // profile). That is the emitter-gate failure class ("target
+            // equivalent" in the exit-code table), not a crash: outcome
+            // failed-gate, exit 3, refusal recorded in the report (ADR-D1 family
+            // evidence, same as an A3 rejection).
+            let emission;
+            try {
+                emission = emitSurface(surface, doc, options.emitProfile ? { profile: options.emitProfile } : {});
+            }
+            catch (error) {
+                if (error instanceof EmitSurfaceError) {
+                    const emitted = { target: "a2ui", refusal: error.message, warnings: [], validations: [] };
+                    emit({ type: "emitted", validations: [], warnings: [] });
+                    const result = finalize("failed-gate", 3, {}, emitted);
+                    emit({ type: "done", outcome: result.report.outcome, exitCode: result.exitCode, report: result.report });
+                    return result;
+                }
+                throw error;
+            }
+            const { messages, warnings } = emission;
+            const validations = [];
+            let gatesPass = true;
+            for (const version of options.a2uiVersions ?? ["0.9.1", "1.0"]) {
+                const { validation } = transform(doc, version, { messages }, options.emitProfile);
+                const gates = validation.gates.map((gate) => ({
+                    gate: A_GATE[gate.name] ?? "A1",
+                    name: gate.name,
+                    pass: gate.pass,
+                    errors: gate.errors,
+                }));
+                if (!validation.pass)
+                    gatesPass = false;
+                validations.push({ a2uiVersion: version, gates });
+            }
+            const emitted = { target: "a2ui", surfaceMessages: { messages }, warnings, validations };
+            emit({ type: "emitted", validations, warnings });
+            const result = gatesPass
+                ? finalize("passed", 0, { surface, surfaceMessages: { messages } }, emitted)
+                : finalize("failed-gate", 3, {}, emitted);
+            emit({ type: "done", outcome: result.report.outcome, exitCode: result.exitCode, report: result.report, surfaceMessages: result.surfaceMessages });
+            return result;
+        }
+        if (index < maxRepairs) {
+            const repair = renderRepairMessage(lint.findings, contract, repairTemplate);
+            repairMessages.push(repair);
+            conversation.push({ role: "assistant", content: generated.raw }, { role: "user", content: repair });
+            emit({ type: "repair", index, message: repair });
+        }
+    }
+    const exhausted = finalize("failed-lint-exhausted", 2);
+    emit({ type: "done", outcome: exhausted.report.outcome, exitCode: exhausted.exitCode, report: exhausted.report });
+    return exhausted;
+}

package/dist/serve.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `dspack-gen serve` — the demo's local pipeline endpoint. Incidental
+ * plumbing: node:http, localhost-only, no framework.
+ *
+ *   POST /run  {prompt?, intent?, model?, fake?, maxRepairs?, noSteering?}
+ *     → NDJSON stream of PipelineEvent lines (start / attempt / repair /
+ *       emitted / done — the `done` event carries the full audit report v1).
+ *
+ * `fake: true` runs the deterministic ScriptedAdapter (golden violating
+ * fixture F1, then the contract's worked example for the requested intent) —
+ * the demo's verification mode and the Playwright gate's backend. Live mode
+ * requires `model` ("ollama:<tag>" | "anthropic:<id>"); as everywhere, no
+ * default model exists in code.
+ *
+ * Hardening (localhost-only is not a security boundary while a browser is
+ * running): CORS is restricted to the demo dev-server origins, request
+ * bodies are size-capped, and event emission can never fail a run.
+ */
+import { createServer } from "node:http";
+export interface ServeOptions {
+    contractPath: string;
+    /** 1–65535 (validated by the CLI); 0 is permitted for tests (ephemeral port). */
+    port?: number;
+}
+export declare function startServer(options: ServeOptions): ReturnType<typeof createServer>;

package/dist/serve.js

@@ -0,0 +1,144 @@
+/**
+ * `dspack-gen serve` — the demo's local pipeline endpoint. Incidental
+ * plumbing: node:http, localhost-only, no framework.
+ *
+ *   POST /run  {prompt?, intent?, model?, fake?, maxRepairs?, noSteering?}
+ *     → NDJSON stream of PipelineEvent lines (start / attempt / repair /
+ *       emitted / done — the `done` event carries the full audit report v1).
+ *
+ * `fake: true` runs the deterministic ScriptedAdapter (golden violating
+ * fixture F1, then the contract's worked example for the requested intent) —
+ * the demo's verification mode and the Playwright gate's backend. Live mode
+ * requires `model` ("ollama:<tag>" | "anthropic:<id>"); as everywhere, no
+ * default model exists in code.
+ *
+ * Hardening (localhost-only is not a security boundary while a browser is
+ * running): CORS is restricted to the demo dev-server origins, request
+ * bodies are size-capped, and event emission can never fail a run.
+ */
+import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { UnknownRuleTypeError } from "./core/lint/index.js";
+import { adapterFor } from "./adapters/index.js";
+import { ScriptedAdapter } from "./adapters/fake.js";
+import { runPipeline } from "./run/orchestrator.js";
+/** Only the demo dev server may read responses cross-origin. */
+const ALLOWED_ORIGINS = new Set(["http://localhost:5173", "http://127.0.0.1:5173"]);
+/** Pipeline requests are small JSON documents; anything bigger is a mistake. */
+const MAX_BODY_BYTES = 64 * 1024;
+export function startServer(options) {
+    const contract = JSON.parse(readFileSync(resolve(options.contractPath), "utf8"));
+    const violating = JSON.parse(readFileSync(resolve("fixtures/golden/violating/F1-dialog-for-delete.dsurface.json"), "utf8"));
+    const server = createServer((request, response) => {
+        const origin = request.headers.origin;
+        if (origin && ALLOWED_ORIGINS.has(origin)) {
+            response.setHeader("access-control-allow-origin", origin);
+            response.setHeader("vary", "origin");
+            response.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
+            response.setHeader("access-control-allow-headers", "content-type");
+        }
+        if (request.method === "OPTIONS") {
+            response.writeHead(204).end();
+            return;
+        }
+        if (request.method === "GET" && request.url === "/health") {
+            response.writeHead(200, { "content-type": "application/json" });
+            response.end(JSON.stringify({ ok: true, contract: contract.name }));
+            return;
+        }
+        if (request.method !== "POST" || request.url !== "/run") {
+            response.writeHead(404).end();
+            return;
+        }
+        let raw = "";
+        let bytes = 0;
+        let tooLarge = false;
+        request.on("data", (chunk) => {
+            if (tooLarge)
+                return;
+            bytes += chunk.length; // byte-accurate: string length counts UTF-16 code units
+            raw += chunk;
+            if (bytes > MAX_BODY_BYTES) {
+                tooLarge = true;
+                response.writeHead(413, { "content-type": "application/json" });
+                response.end(JSON.stringify({ error: `request body exceeds ${MAX_BODY_BYTES} bytes` }));
+                request.destroy();
+            }
+        });
+        request.on("end", () => {
+            if (tooLarge)
+                return;
+            void (async () => {
+                let body;
+                try {
+                    body = raw ? JSON.parse(raw) : {};
+                }
+                catch {
+                    response.writeHead(400, { "content-type": "application/json" });
+                    response.end(JSON.stringify({ error: "invalid JSON body" }));
+                    return;
+                }
+                const intent = body.intent ?? "destructive-action";
+                // Untrusted JSON: booleans are strict, numbers are validated.
+                const fake = body.fake === true;
+                const noSteering = body.noSteering === true;
+                if (body.maxRepairs !== undefined && (!Number.isInteger(body.maxRepairs) || body.maxRepairs < 0)) {
+                    response.writeHead(400, { "content-type": "application/json" });
+                    response.end(JSON.stringify({ error: "maxRepairs must be a non-negative integer" }));
+                    return;
+                }
+                let adapter;
+                if (fake) {
+                    // The scripted repair must land on the contract's worked example
+                    // FOR THIS INTENT — fail fast instead of scripting `undefined`.
+                    const example = (contract.examples ?? []).find((e) => e.intent === intent);
+                    if (!example) {
+                        response.writeHead(400, { "content-type": "application/json" });
+                        response.end(JSON.stringify({ error: `contract has no example for intent '${intent}' — fake mode needs one` }));
+                        return;
+                    }
+                    adapter = new ScriptedAdapter([{ output: violating }, { output: example.surface }]);
+                }
+                else if (typeof body.model === "string") {
+                    adapter = adapterFor(body.model);
+                }
+                else {
+                    response.writeHead(400, { "content-type": "application/json" });
+                    response.end(JSON.stringify({ error: "either fake: true or model: 'ollama:<tag>|anthropic:<id>' is required" }));
+                    return;
+                }
+                response.writeHead(200, { "content-type": "application/x-ndjson", "cache-control": "no-store" });
+                const send = (event) => {
+                    response.write(JSON.stringify(event) + "\n");
+                };
+                try {
+                    await runPipeline({
+                        contract,
+                        intent,
+                        prompt: body.prompt ?? "a screen to delete my account",
+                        adapter,
+                        maxRepairs: body.maxRepairs,
+                        compile: { omitRuleSteering: noSteering },
+                        onEvent: send,
+                    });
+                }
+                catch (error) {
+                    send({
+                        type: "error",
+                        exitCode: error instanceof UnknownRuleTypeError ? 4 : 1,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                response.end();
+            })();
+        });
+    });
+    const port = options.port ?? 8787;
+    server.listen(port, "127.0.0.1", () => {
+        const address = server.address();
+        const actual = typeof address === "object" && address ? address.port : port;
+        console.error(`dspack-gen serve: http://127.0.0.1:${actual} (contract: ${contract.name})`);
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@aestheticfunction/dspack-gen",
+  "version": "0.1.0",
+  "description": "Generation + governance pipeline for dspack contracts: prompt/context compiler, surface gates S1\u2013S3, bounded repair, protocol emission, audit reports.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aestheticfunction/dspack-gen.git"
+  },
+  "homepage": "https://github.com/aestheticfunction/dspack-gen#readme",
+  "bugs": {
+    "url": "https://github.com/aestheticfunction/dspack-gen/issues"
+  },
+  "keywords": [
+    "dspack",
+    "design-systems",
+    "generative-ui",
+    "governance",
+    "a2ui",
+    "llm"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "dspack-gen": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run test",
+    "test": "vitest run",
+    "context": "tsx src/cli.ts context",
+    "smoke:ollama": "tsx scripts/smoke-ollama.ts",
+    "demo:e2e": "playwright test",
+    "eval": "tsx src/eval/run.ts",
+    "eval:assert": "tsx src/eval/assert.ts",
+    "check:sync": "node scripts/check-sync.mjs"
+  },
+  "dependencies": {
+    "@aestheticfunction/dspack-emit": "^0.3.1",
+    "@anthropic-ai/sdk": "^0.109.1",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "undici": "^6.27.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/adapters/anthropic.ts

@@ -0,0 +1,88 @@
+/**
+ * Anthropic adapter — hosted generation via the official SDK with
+ * schema-constrained output (`output_config.format`, type json_schema).
+ *
+ * The generation schema is compatible by construction: depth-unrolled (the
+ * structured-outputs API rejects recursive schemas) and additionalProperties:
+ * false on every object. No sampling parameters are sent — they are removed
+ * on current Claude models. `stop_reason: "refusal"` is surfaced as a typed
+ * AdapterOutputError (never retried silently; retries are the repair loop's
+ * job and only for lint findings).
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import {
+  AdapterOutputError,
+  parseJsonOutput,
+  type FetchLike,
+  type GenerateRequest,
+  type GenerateResult,
+  type GenerationAdapter,
+} from "./types.js";
+
+export interface AnthropicAdapterOptions {
+  /** Required — no default model exists in code (ADR-9 as amended). */
+  model: string;
+  /** Defaults to the SDK's environment resolution (ANTHROPIC_API_KEY, auth token, profile). */
+  apiKey?: string;
+  baseURL?: string;
+  fetch?: FetchLike;
+}
+
+export class AnthropicAdapter implements GenerationAdapter {
+  readonly id: string;
+  private readonly model: string;
+  private readonly client: Anthropic;
+
+  constructor(options: AnthropicAdapterOptions) {
+    if (!options.model) throw new Error("AnthropicAdapter requires an explicit model id (config/env/flag)");
+    this.model = options.model;
+    this.client = new Anthropic({
+      apiKey: options.apiKey,
+      baseURL: options.baseURL,
+      fetch: options.fetch as never,
+    });
+    this.id = `anthropic:${this.model}`;
+  }
+
+  async generate(request: GenerateRequest): Promise<GenerateResult> {
+    // Typed transport: SDK connection/API errors surface as failed-adapter
+    // outcomes (with a report), never as raw exceptions that kill a matrix.
+    let response: unknown;
+    try {
+      response = await this.client.messages.create({
+        model: this.model,
+        max_tokens: request.params?.maxTokens ?? 16000,
+        system: request.system,
+        messages: request.messages,
+        output_config: {
+          format: { type: "json_schema", schema: request.jsonSchema as never },
+        },
+      } as never);
+    } catch (error) {
+      if (error instanceof AdapterOutputError) throw error;
+      const name = error instanceof Error ? error.constructor.name : "unknown";
+      throw new AdapterOutputError(this.id, `transport failure (${name}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    const message = response as Anthropic.Message;
+    if (message.stop_reason === "refusal") {
+      throw new AdapterOutputError(this.id, "model refused the request (stop_reason: refusal)");
+    }
+    const raw = message.content
+      .filter((block): block is Anthropic.TextBlock => block.type === "text")
+      .map((block) => block.text)
+      .join("");
+    if (raw === "") throw new AdapterOutputError(this.id, "empty model output");
+    if (message.stop_reason === "max_tokens") {
+      throw new AdapterOutputError(this.id, "output truncated (stop_reason: max_tokens) — raise params.maxTokens", raw);
+    }
+
+    return {
+      json: parseJsonOutput(this.id, raw),
+      raw,
+      model: message.model,
+      usage: { inputTokens: message.usage.input_tokens, outputTokens: message.usage.output_tokens },
+      meta: { provider: "anthropic", stop_reason: message.stop_reason },
+    };
+  }
+}

package/src/adapters/fake.ts

@@ -0,0 +1,32 @@
+/**
+ * Scripted adapter — the deterministic instrument behind CI gates, the demo's
+ * verification mode, and the eval harness's golden runs. Returns the scripted
+ * outputs in order; a script entry of `{ error: "..." }` raises a typed
+ * AdapterOutputError instead.
+ */
+import { AdapterOutputError, type GenerateRequest, type GenerateResult, type GenerationAdapter } from "./types.js";
+
+export type ScriptEntry = { output: unknown } | { error: string };
+
+export class ScriptedAdapter implements GenerationAdapter {
+  readonly id = "fake:scripted";
+  /** Every request received, for assertions on repair-loop conversation state. */
+  readonly requests: GenerateRequest[] = [];
+  private cursor = 0;
+
+  constructor(private readonly script: ScriptEntry[]) {}
+
+  async generate(request: GenerateRequest): Promise<GenerateResult> {
+    this.requests.push(request);
+    const entry = this.script[this.cursor++];
+    if (!entry) throw new Error(`ScriptedAdapter: script exhausted after ${this.script.length} generation(s)`);
+    if ("error" in entry) throw new AdapterOutputError(this.id, entry.error);
+    return {
+      json: entry.output,
+      raw: JSON.stringify(entry.output),
+      model: "fake-model",
+      usage: { inputTokens: 0, outputTokens: 0 },
+      meta: { provider: "fake" },
+    };
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,13 @@
+export * from "./types.js";
+export { OllamaAdapter, type OllamaAdapterOptions } from "./ollama.js";
+export { AnthropicAdapter, type AnthropicAdapterOptions } from "./anthropic.js";
+
+import { OllamaAdapter } from "./ollama.js";
+import { AnthropicAdapter } from "./anthropic.js";
+import { parseModelRef, type GenerationAdapter } from "./types.js";
+
+/** Build an adapter from a `--model` reference (ollama:<id> | anthropic:<id>). */
+export function adapterFor(modelRef: string): GenerationAdapter {
+  const { provider, model } = parseModelRef(modelRef);
+  return provider === "ollama" ? new OllamaAdapter({ model }) : new AnthropicAdapter({ model });
+}