@aestheticfunction/dspack-gen 0.1.0

package/src/adapters/ollama.ts

@@ -0,0 +1,123 @@
+/**
+ * Ollama adapter — local generation via structured outputs (`format` = the
+ * generation schema on /api/chat). Mandatory for the local path per the plan;
+ * there is no unconstrained-JSON fallback in this design.
+ *
+ * S0 spike caveat carried here: on mlx-engine models Ollama silently ignores
+ * `format`. The adapter cannot detect the engine from the chat response, so
+ * it records the model tag in `meta` and relies on gates S1/S2 to catch
+ * unconstrained output; non-JSON output raises AdapterOutputError.
+ */
+import { Agent } from "undici";
+import {
+  AdapterOutputError,
+  parseJsonOutput,
+  type FetchLike,
+  type GenerateRequest,
+  type GenerateResult,
+  type GenerationAdapter,
+} from "./types.js";
+
+/**
+ * Local inference is legitimately slow: a single 35B generation can exceed
+ * undici's default 300s headersTimeout, which killed runs at exactly ~301s
+ * in the 2026-07-03 eval (reports with zero attempts, "fetch failed").
+ * One long-lived dispatcher with the header/body timeouts raised to an hour
+ * — a deliberate ceiling, not "no timeout": a truly hung server should
+ * still fail rather than block a matrix forever.
+ */
+const LOCAL_INFERENCE_TIMEOUT_MS = 60 * 60 * 1000;
+
+/** undici's fetch-init extension, typed so the rest of the init stays checked. */
+interface DispatchedRequestInit extends RequestInit {
+  dispatcher?: Agent;
+}
+const localInferenceDispatcher = new Agent({
+  headersTimeout: LOCAL_INFERENCE_TIMEOUT_MS,
+  bodyTimeout: LOCAL_INFERENCE_TIMEOUT_MS,
+});
+
+export interface OllamaAdapterOptions {
+  /** Required — no default model exists in code (ADR-9 as amended). */
+  model: string;
+  /** Defaults to OLLAMA_HOST env or http://localhost:11434. */
+  host?: string;
+  fetch?: FetchLike;
+}
+
+interface OllamaChatResponse {
+  model?: string;
+  message?: { content?: string };
+  prompt_eval_count?: number;
+  eval_count?: number;
+  total_duration?: number;
+  load_duration?: number;
+  prompt_eval_duration?: number;
+  eval_duration?: number;
+}
+
+export class OllamaAdapter implements GenerationAdapter {
+  readonly id: string;
+  private readonly model: string;
+  private readonly host: string;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(options: OllamaAdapterOptions) {
+    if (!options.model) throw new Error("OllamaAdapter requires an explicit model id (config/env/flag)");
+    this.model = options.model;
+    this.host = options.host ?? process.env.OLLAMA_HOST ?? "http://localhost:11434";
+    this.fetchImpl = options.fetch ?? fetch;
+    this.id = `ollama:${this.model}`;
+  }
+
+  async generate(request: GenerateRequest): Promise<GenerateResult> {
+    const body = {
+      model: this.model,
+      stream: false,
+      format: request.jsonSchema,
+      options: { temperature: request.params?.temperature ?? 0.2 },
+      messages: [{ role: "system", content: request.system }, ...request.messages],
+    };
+    // The whole transport exchange is typed: a rejected fetch (connection
+    // reset, timeout under a large model load) must surface as a
+    // failed-adapter outcome with a report, never as a raw exception that
+    // kills a whole eval matrix (the 2026-07-03 live-run crash).
+    let data: OllamaChatResponse;
+    try {
+      const init: DispatchedRequestInit = {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        // undici extension of fetch(init); ignored by injected test fetches.
+        dispatcher: localInferenceDispatcher,
+      };
+      const response = await this.fetchImpl(`${this.host}/api/chat`, init);
+      if (!response.ok) {
+        // Body read can itself fail on a broken stream — keep the HTTP
+        // status in the error either way.
+        const detail = await response.text().catch(() => "(response body unreadable)");
+        throw new AdapterOutputError(this.id, `HTTP ${response.status}: ${detail.slice(0, 300)}`);
+      }
+      data = (await response.json()) as OllamaChatResponse;
+    } catch (error) {
+      if (error instanceof AdapterOutputError) throw error;
+      throw new AdapterOutputError(this.id, `transport failure: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const raw = data.message?.content ?? "";
+    if (raw === "") throw new AdapterOutputError(this.id, "empty model output");
+
+    return {
+      json: parseJsonOutput(this.id, raw),
+      raw,
+      model: data.model ?? this.model,
+      usage: { inputTokens: data.prompt_eval_count, outputTokens: data.eval_count },
+      meta: {
+        provider: "ollama",
+        total_duration: data.total_duration,
+        load_duration: data.load_duration,
+        prompt_eval_duration: data.prompt_eval_duration,
+        eval_duration: data.eval_duration,
+      },
+    };
+  }
+}

package/src/adapters/types.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 class AdapterOutputError extends Error {
+  constructor(
+    readonly adapterId: string,
+    message: string,
+    readonly rawHead?: string,
+  ) {
+    super(`[${adapterId}] ${message}${rawHead ? ` (output head: ${JSON.stringify(rawHead.slice(0, 200))})` : ""}`);
+    this.name = "AdapterOutputError";
+  }
+}
+
+/** Injectable for offline, deterministic tests. */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export function parseJsonOutput(adapterId: string, raw: string): unknown {
+  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: string): { provider: "ollama" | "anthropic"; model: string } {
+  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/src/audit/report.ts

@@ -0,0 +1,139 @@
+/**
+ * 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";
+import type { Contract } from "../core/contract.js";
+import type { Finding, GateReport } from "../core/lint/findings.js";
+
+export 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 function sha256(value: unknown): string {
+  return createHash("sha256").update(typeof value === "string" ? value : JSON.stringify(value)).digest("hex");
+}
+
+export function contractDigest(contract: Contract): { name: string; dspack: string; sha256: string } {
+  return { name: contract.name, dspack: contract.dspack, sha256: sha256(contract as unknown as Record<string, unknown>) };
+}
+
+/** Human view of the JSON artifact — derived, never the source of truth. */
+export function renderMarkdown(report: AuditReportV1): string {
+  const lines: string[] = [
+    `# 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/src/cli.ts

@@ -0,0 +1,191 @@
+#!/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 type { Contract } from "./core/contract.js";
+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: string): never {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+const BOOLEAN_FLAGS = new Set(["no-steering"]);
+
+function parseFlags(argv: string[]): Map<string, string> {
+  const flags = new Map<string, string>();
+  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: Map<string, string>): void {
+  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")) as Contract;
+  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: Map<string, string>): void {
+  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")) as Contract;
+  const surface = JSON.parse(readFileSync(resolve(surfacePath), "utf8")) as unknown;
+
+  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: Map<string, string>): number | undefined {
+  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: Map<string, string>): Promise<void> {
+  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")) as Contract;
+  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(): void {
+  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: number | undefined;
+    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();