dspack-gen

Generation + governance pipeline for dspack contracts. Compiles a dspack v0.3/v0.4 contract into generation context, generates dspack surfaces via schema-constrained LLMs (Ollama local or hosted — interchangeable adapters), lints them deterministically against the contract's governance rules, repairs bounded, emits to protocols (A2UI and json-render via dspack-emit), and produces a versioned audit report.

A2UI defines what can render. dspack defines what is correct.

Status: Milestones 1 through 3 complete. Tags m1, m2, and m3; write-ups in docs/m1-report.md, docs/m2-report.md, and docs/m3-report.md, findings in docs/findings.md. M4 is trigger-gated on A2UI v1.0 leaving Candidate status. The emitter is consumed from npm as @aestheticfunction/dspack-emit (renamed from @aestheticfunction/dspack-to-a2ui with the ADR-D2 repo rename; the old package is deprecated with a pointer).

The three layers (never collapse them)

1. Schema answers "can this object exist" — the generation schema encodes vocabulary and shape only, never governance.
2. Linter answers "is this object correct" — deterministic typed rules (gate S3), each with a rationale.
3. Renderer answers "can this render" — protocol emitters compile the surface; the target's gates (A1–A3 for A2UI) validate the result.

Gates

| Gate | Check | Where | |---|---|---| | S1 | generic dspack surface schema | here (pre-emission) | | S2 | contract vocabulary (components, sub-components, props, enum values, slots) | here (pre-emission) | | S3 | governance rules (typed, deterministic, rationale-bearing) | here (pre-emission) | | A1–A3 | schema-compile / catalog-shape / instance validation | dspack-emit (per emitted target) |

S1/S2 are checks on any produced surface; constrained decoding may implement S2 during generation but the gates are always reported independently — the S0 spike found Ollama's mlx engine silently ignoring format, which is exactly why.

CLI

npm run context -- --dspack fixtures/shadcn.v0_4.dspack.json --intent destructive-action
# prints { system, schema, fewshot } — the compiled generation context

lint (S1–S3) and run (full pipeline) land in later M1 PRs.

Exit codes (whole CLI surface)

| Code | Meaning | |---|---| | 0 | clean | | 1 | internal / usage error | | 2 | governance failure (any S-gate error) | | 3 | emitter-gate failure (A1–A3 or target equivalent) | | 4 | unknown rule type (fail-loud; never silently skipped) |

(Distinct from dspack-emit's exit codes, where 3 = strict-coverage failure and 4 = surface-emission failure.)

Eval harness

npm run eval -- --adapter fake --matrix eval/matrix.fake.json   # deterministic; the CI gate
npm run eval -- --adapter live --matrix eval/matrix.json        # documented live run; never CI
npm run eval -- --adapter live --matrix eval/matrix.json --out out/eval/<dir> --resume   # resume an interrupted run
npm run eval:assert -- --results out/eval/fake/results.json --model <ref> --min-repair-success 0.9

Every cell run goes through the same runPipeline as the CLI and demo; the harness only iterates and aggregates. Model ids live in eval/matrix.json (config), never in code. Per cell (model × prompt × repair template, runsPerCell runs): schema-validity, first-attempt-violation, repair-success (null over zero violations), end-to-end pass rates, and the count of S3-clean surfaces refused by emitter gates (the ADR-D1 signal; p10–p12 probe it deliberately). Prompts span repair shapes — substitution, addition, deletion, restructuring — and every prompt crosses the two ADR-7 repair templates (standard vs permit-restructuring, a one-instruction-line delta recorded in each audit report). One run can never kill the matrix: adapter transport failures are typed (failed-adapter, with a report) and anything that still escapes a run is contained as an explicit error run — visible in the distribution with a retained .error.json, excluded from the model-behavior rate denominators (errorRuns reports the count). --resume skips already-retained reports and retries error records. Every run's audit report is retained under out/eval/…/reports/; results.json is the artifact, report.md the derived view; findings go to docs/findings.md at measured strength. The hosted-model eval:assert threshold is the only hard eval gate in M2; local models are report-only.

Library

npm install @aestheticfunction/dspack-gen

ESM only, Node >= 20. The root entry is the full pipeline:

import { runPipeline, adapterFor } from "@aestheticfunction/dspack-gen";
import { readFileSync } from "node:fs";

const contract = JSON.parse(readFileSync("astryx.dspack.json", "utf8"));
const result = await runPipeline({
  contract,
  intent: "destructive-action",
  prompt: "a screen to delete a project",
  adapter: adapterFor("ollama:gemma3"),
});
console.log(result.report.outcome, result.exitCode);

@aestheticfunction/dspack-gen/core is the zero-network, emitter-free subpath (compiler + linter) that ds-mcp consumes without breaking its read-only/no-network security posture. The boundary is enforced by src/core/core-boundary.test.ts:

import { compileContext, lintSurface } from "@aestheticfunction/dspack-gen/core";

The CLI installs as dspack-gen (same commands as the repo scripts): context, lint, run, serve. Outside this repository, always pass --dspack <contract> (the serve default path points at a repo fixture).

Development

npm ci
npm test          # vitest: golden context, generation-schema behavior, core boundary
npm run check:sync  # contract-copy drift check vs the dspack repo (CI-run; --write re-syncs)

fixtures/shadcn.v0_4.dspack.json is a byte copy of the spec repo's examples/shadcn-ui.dspack.json; CI fails loudly if they diverge (dspack-gen#7). After --write, regenerate the derived goldens (context golden, F-fixture expected outputs, eval fake golden) and commit the sync + regeneration together.

License

Apache-2.0. Copyright 2026 Aesthetic Function, LLC.