@aestheticfunction/dspack-gen 0.1.0

package/src/core/compiler.ts

@@ -0,0 +1,205 @@
+/**
+ * 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 ExampleEntry,
+  type IntentEntry,
+  type RuleEntry,
+  categoryIndex,
+  enumValues,
+  getIntent,
+} from "./contract.js";
+import { buildGenerationSchema, 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 function applicableRules(contract: Contract, intentId: string): RuleEntry[] {
+  return (contract.rules ?? []).filter(
+    (rule) => !rule.appliesTo || rule.appliesTo.intents.includes(intentId),
+  );
+}
+
+export function compileContext(
+  contract: Contract,
+  intentId: string,
+  options: CompileOptions = {},
+): CompiledContext {
+  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: ExampleEntry): FewshotMessage[] {
+  return [
+    { role: "user", content: example.prompt ?? example.description ?? example.id },
+    { role: "assistant", content: JSON.stringify(example.surface) },
+  ];
+}
+
+function renderSystemPrompt(
+  contract: Contract,
+  intent: IntentEntry,
+  rules: RuleEntry[],
+  options: CompileOptions,
+): string {
+  const lines: string[] = [
+    `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: RuleEntry, contract?: Contract): string {
+  switch (rule.type) {
+    case "component-choice": {
+      const r = rule as { require?: string[]; forbid?: string[] };
+      const parts: string[] = [];
+      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 as { component: string; requiredSubComponents?: Array<{ id: string }>; requiredProps?: Array<{ prop: string; oneOf: unknown[] }> };
+      const needs: string[] = [];
+      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 as {
+        component: string;
+        forbiddenDescendants?: string[];
+        forbiddenProps?: Array<{ prop: string; values: unknown[] }>;
+        forbiddenCategories?: string[];
+      };
+      const parts: string[] = [];
+      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 as {
+        component: string;
+        within?: string;
+        requiredText?: true;
+        textScope?: "self" | "subtree";
+        requiredProps?: Array<{ prop: string; oneOf?: unknown[] }>;
+      };
+      const scope = r.within ? `At least one ${r.component} inside each ${r.within}` : `Every ${r.component}`;
+      const needs: string[] = [];
+      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}.`;
+  }
+}

package/src/core/contract.ts

@@ -0,0 +1,205 @@
+/**
+ * Minimal dspack v0.3/v0.4 contract types — exactly the fields the pipeline
+ * reads. Deliberately local: `core` (compiler + linter) is protocol-neutral
+ * and depends on no emitter and no network module (enforced by core-boundary
+ * tests). dspack documents may carry more; unknown properties are ignored per
+ * dspack conformance rules.
+ */
+
+export interface Contract {
+  dspack: string;
+  name: string;
+  description?: string;
+  tokens?: Record<string, { values?: Record<string, { value?: unknown }> }>;
+  components?: Record<string, ContractComponent>;
+  /** v0.4: contract-defined category registry (spec v0.4 §3). */
+  categories?: Record<string, { name?: string; description: string }>;
+  patterns?: ContractPattern[];
+  intents?: IntentEntry[];
+  rules?: RuleEntry[];
+  examples?: ExampleEntry[];
+  [k: string]: unknown;
+}
+
+export interface ContractComponent {
+  name: string;
+  description: string;
+  props?: Record<string, ContractProp>;
+  composition?: { subComponents?: SubComponent[]; notes?: string };
+  /** v0.4: membership in registered categories. */
+  categories?: string[];
+  [k: string]: unknown;
+}
+
+export interface ContractProp {
+  type: string;
+  description?: string;
+  values?: Array<string | number | boolean | { value: unknown; description?: string }>;
+  default?: unknown;
+  [k: string]: unknown;
+}
+
+export interface SubComponent {
+  id: string;
+  name: string;
+  description?: string;
+  required?: boolean;
+  slot?: string;
+  acceptsChildren?: string;
+  /** v0.4: membership in registered categories. */
+  categories?: string[];
+}
+
+export interface ContractPattern {
+  id: string;
+  name?: string;
+  guidance?: string;
+  [k: string]: unknown;
+}
+
+export interface IntentEntry {
+  id: string;
+  name?: string;
+  description: string;
+  relatedPatterns?: string[];
+  tags?: string[];
+}
+
+export type RuleSeverity = "must" | "should";
+export type RuleType = "component-choice" | "required-composition" | "forbidden-composition" | "required-props";
+
+export interface RuleBase {
+  id: string;
+  type: string; // validated against RuleType by the linter; unknown => hard error
+  severity: RuleSeverity;
+  rationale: string;
+  appliesTo?: { intents: string[] };
+  examples?: string[];
+  tags?: string[];
+}
+
+export interface ComponentChoiceRule extends RuleBase {
+  type: "component-choice";
+  require?: string[];
+  forbid?: string[];
+}
+
+export interface RequiredCompositionRule extends RuleBase {
+  type: "required-composition";
+  component: string;
+  requiredSubComponents?: Array<{ id: string; min?: number }>;
+  requiredProps?: Array<{ on?: string; prop: string; oneOf: unknown[] }>;
+}
+
+export interface ForbiddenCompositionRule extends RuleBase {
+  type: "forbidden-composition";
+  component: string;
+  forbiddenDescendants?: string[];
+  forbiddenProps?: Array<{ on?: string; prop: string; values: unknown[] }>;
+  /** v0.4: forbid descendants by registered category (spec v0.4 §4.2). */
+  forbiddenCategories?: string[];
+}
+
+/**
+ * v0.4 required-props (spec v0.4 §4.1): content every instance of `component`
+ * must carry DIRECTLY — its own `text` field and/or directly-present props.
+ * The one rule type whose `component` accepts a sub-component id.
+ */
+export interface RequiredPropsRule extends RuleBase {
+  type: "required-props";
+  component: string;
+  within?: string;
+  requiredText?: true;
+  /** v0.4 amendment (2026-07-04): where requiredText looks. Default "self". */
+  textScope?: "self" | "subtree";
+  requiredProps?: Array<{ prop: string; oneOf?: unknown[] }>;
+}
+
+export type RuleEntry =
+  | ComponentChoiceRule
+  | RequiredCompositionRule
+  | ForbiddenCompositionRule
+  | RequiredPropsRule
+  | RuleBase;
+
+export interface ExampleEntry {
+  id: string;
+  intent: string;
+  name?: string;
+  description?: string;
+  prompt?: string;
+  surface: Surface;
+}
+
+/** dspack surface v0.1 (schema: dspack repo, dspack.surface.v0_1.schema.json). */
+export interface Surface {
+  dspackSurface: string;
+  system: string;
+  intent: string;
+  root: SurfaceNode;
+}
+
+export interface SurfaceNode {
+  component: string;
+  id?: string;
+  props?: Record<string, unknown>;
+  text?: string;
+  children?: SurfaceNode[];
+  slots?: Record<string, SurfaceNode[]>;
+}
+
+/** Bare enum values from a prop descriptor (valueDescriptor objects unwrapped). */
+export function enumValues(prop: ContractProp): unknown[] | null {
+  if (prop.type !== "enum" || !Array.isArray(prop.values)) return null;
+  return prop.values.map((v) => (v && typeof v === "object" ? (v as { value: unknown }).value : v));
+}
+
+/** All sub-component ids of the contract, mapped to their parent component id. */
+export function subComponentIndex(contract: Contract): Map<string, string> {
+  const index = new Map<string, string>();
+  for (const [id, component] of Object.entries(contract.components ?? {})) {
+    for (const sub of component.composition?.subComponents ?? []) index.set(sub.id, id);
+  }
+  return index;
+}
+
+/**
+ * Sub-component ids declared by more than one component, with all declaring
+ * parents. Spec v0.3 §5 makes document-wide uniqueness normative for
+ * contracts using governance blocks: S2 and rule resolution work by id alone
+ * and must never depend on object iteration order.
+ */
+export function duplicateSubComponentIds(contract: Contract): Map<string, string[]> {
+  const parents = new Map<string, string[]>();
+  for (const [id, component] of Object.entries(contract.components ?? {})) {
+    for (const sub of component.composition?.subComponents ?? []) {
+      parents.set(sub.id, [...(parents.get(sub.id) ?? []), id]);
+    }
+  }
+  return new Map([...parents].filter(([, declaredBy]) => declaredBy.length > 1));
+}
+
+/**
+ * Category memberships by component/sub-component id (v0.4). Ids without
+ * memberships are absent. Resolution is through the contract at lint time —
+ * categories never appear in surfaces (spec v0.4 §3).
+ */
+export function categoryIndex(contract: Contract): Map<string, string[]> {
+  const index = new Map<string, string[]>();
+  for (const [id, component] of Object.entries(contract.components ?? {})) {
+    if (component.categories?.length) index.set(id, component.categories);
+    for (const sub of component.composition?.subComponents ?? []) {
+      if (sub.categories?.length) index.set(sub.id, sub.categories);
+    }
+  }
+  return index;
+}
+
+export function getIntent(contract: Contract, intentId: string): IntentEntry {
+  const intent = (contract.intents ?? []).find((i) => i.id === intentId);
+  if (!intent) {
+    const known = (contract.intents ?? []).map((i) => i.id).join(", ") || "(none)";
+    throw new Error(`intent '${intentId}' is not registered in the contract (known: ${known})`);
+  }
+  return intent;
+}

package/src/core/generation-schema.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-contract generation schema: the JSON Schema handed to constrained
+ * decoding (Ollama `format`, hosted output schemas).
+ *
+ * Derivation from the contract: full component + sub-component vocabulary as
+ * anyOf branches, per-component prop enums, `intent`/`system`/`dspackSurface`
+ * as consts, and recursion depth-unrolled ($defs node_0..node_{D-1}; the last
+ * level is a leaf) so the schema is non-recursive by construction. Default
+ * depth 6 was confirmed by the S0 spike (docs/spike-structured-outputs.md):
+ * depths 3–8 compile and are enforced on grammar-backed engines.
+ *
+ * The three layers, deliberately: this schema encodes vocabulary and shape
+ * ONLY — never governance. Encoding rules here would make violations
+ * unobservable and the audit trail vacuous. Gate S2 is *defined* as a check on
+ * the produced surface; this schema may be reused to implement it, but S2 is
+ * always reported independently.
+ *
+ * Spike-inherited simplifications (documented): children accept the full
+ * vocabulary at every level (per-parent child constraints are S3 territory),
+ * `text` is allowed on every node, and `slots` are not generated (composition
+ * is expressed via children; the surface schema still accepts slots on
+ * hand-authored surfaces).
+ */
+import { type Contract, type ContractComponent, enumValues } from "./contract.js";
+
+export const DEFAULT_UNROLL_DEPTH = 6;
+
+export interface GenerationSchemaOptions {
+  /** Levels of tree nesting the schema admits. S0-confirmed default: 6. */
+  depth?: number;
+}
+
+type Json = Record<string, unknown>;
+
+export function buildGenerationSchema(
+  contract: Contract,
+  intentId: string,
+  options: GenerationSchemaOptions = {},
+): Json {
+  const depth = options.depth ?? DEFAULT_UNROLL_DEPTH;
+  if (!Number.isInteger(depth) || depth < 1) throw new Error(`invalid unroll depth ${depth}`);
+
+  const components = contract.components ?? {};
+  const $defs: Json = {};
+  for (let level = 0; level < depth; level++) {
+    const branches: Json[] = [];
+    for (const [id, component] of Object.entries(components)) {
+      branches.push(branch(id, componentProps(component), level, depth));
+      for (const sub of component.composition?.subComponents ?? []) {
+        branches.push(branch(sub.id, null, level, depth));
+      }
+    }
+    $defs[`node_${level}`] = { anyOf: branches };
+  }
+
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    additionalProperties: false,
+    required: ["dspackSurface", "system", "intent", "root"],
+    properties: {
+      dspackSurface: { const: "0.1" },
+      system: { const: contract.name },
+      intent: { const: intentId },
+      root: { $ref: "#/$defs/node_0" },
+    },
+    $defs,
+  };
+}
+
+function componentProps(component: ContractComponent): Json | null {
+  const entries = Object.entries(component.props ?? {});
+  if (entries.length === 0) return null;
+  const properties: Json = {};
+  for (const [name, descriptor] of entries) {
+    const values = enumValues(descriptor);
+    properties[name] = values
+      ? { enum: values }
+      : descriptor.type === "boolean"
+        ? { type: "boolean" }
+        : descriptor.type === "number"
+          ? { type: "number" }
+          : { type: "string" };
+  }
+  return { type: "object", additionalProperties: false, properties };
+}
+
+function branch(id: string, props: Json | null, level: number, depth: number): Json {
+  const properties: Json = {
+    component: { const: id },
+    id: { type: "string" },
+    text: { type: "string" },
+  };
+  if (props) properties.props = props;
+  if (level < depth - 1) {
+    properties.children = { type: "array", items: { $ref: `#/$defs/node_${level + 1}` } };
+  }
+  return { type: "object", additionalProperties: false, required: ["component"], properties };
+}

package/src/core/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @aestheticfunction/dspack-gen/core — the zero-network, emitter-free subset:
+ * prompt/context compiler (+ the governance linter, from PR-4 on).
+ *
+ * ds-mcp's `get-generation-context` / `validate-ui` tools import exactly this
+ * subpath; its no-network/read-only invariants depend on this boundary, which
+ * is enforced by src/core/core-boundary.test.ts.
+ */
+export * from "./contract.js";
+export * from "./generation-schema.js";
+export * from "./compiler.js";
+export * from "./lint/index.js";

package/src/core/lint/findings.ts

@@ -0,0 +1,80 @@
+/**
+ * Lint findings and the gate report — ONE object, two serializations (ADR-7):
+ * the JSON here is embedded verbatim in audit reports and rendered
+ * deterministically into repair feedback; `renderText` is the human CLI view.
+ *
+ * Severity carries both faces (ADR-11): `requirement` is the contract's
+ * RFC 2119 term (must|should), `level` the tool mapping (error|warn).
+ */
+import type { RuleSeverity } from "../contract.js";
+
+export type FindingLevel = "error" | "warn";
+
+export const LEVEL_OF: Record<RuleSeverity, FindingLevel> = {
+  must: "error",
+  should: "warn",
+};
+
+export interface FindingLocation {
+  /** Path from the surface root, e.g. `$.root.children[0]`; `$.root` for surface-wide findings. */
+  path: string;
+  /** The component id at the location, or "surface" for surface-wide findings. */
+  component: string;
+  nodeId?: string;
+}
+
+export interface Finding {
+  ruleId: string;
+  type: string;
+  requirement: RuleSeverity;
+  level: FindingLevel;
+  message: string;
+  rationale: string;
+  location: FindingLocation;
+  exampleIds: string[];
+}
+
+export type GateName = "S1" | "S2" | "S3";
+export type GateStatus = "PASS" | "FAIL" | "SKIPPED";
+
+export interface GateReport {
+  gate: GateName;
+  name: string;
+  status: GateStatus;
+  /** S1/S2 error strings; S3 uses `findings` instead. */
+  errors?: string[];
+}
+
+export interface LintReport {
+  gates: GateReport[];
+  findings: Finding[];
+  /** Errors only (warn findings never fail the lint in v0.3). */
+  errorCount: number;
+  warnCount: number;
+  pass: boolean;
+}
+
+export function renderText(report: LintReport): string {
+  const lines: string[] = [];
+  for (const gate of report.gates) {
+    lines.push(`gate ${gate.gate} ${gate.name.padEnd(21)} ${gate.status}`);
+    for (const error of gate.errors ?? []) lines.push(`  ✖ ${error}`);
+  }
+  for (const finding of report.findings) {
+    const mark = finding.level === "error" ? "✖" : "▲";
+    lines.push(`${mark} ${finding.level} [${finding.requirement}]  ${finding.ruleId}  [${finding.type}]`);
+    const where = finding.location.nodeId
+      ? `${finding.location.path}  (component: ${finding.location.component}, id: "${finding.location.nodeId}")`
+      : `${finding.location.path}  (component: ${finding.location.component})`;
+    lines.push(`   at ${where}`);
+    lines.push(`   ${finding.message}`);
+    lines.push(`   Rationale: ${finding.rationale}`);
+    if (finding.exampleIds.length) lines.push(`   See example: ${finding.exampleIds.join(", ")}`);
+  }
+  lines.push(
+    report.pass
+      ? `lint: PASS — 0 error(s), ${report.warnCount} warning(s)`
+      : `lint: FAIL — ${report.errorCount} error(s), ${report.warnCount} warning(s)`,
+  );
+  return lines.join("\n");
+}

package/src/core/lint/index.ts

@@ -0,0 +1,80 @@
+/**
+ * The surface gates, run in order and independently reported (never implicit
+ * steps inside generation):
+ *   S1 — generic surface schema (vendored dspack.surface.v0_1)
+ *   S2 — contract vocabulary
+ *   S3 — governance rules (typed evaluators, registry in rules.ts)
+ *
+ * S1 failure skips S2/S3 (the tree shape is not trustworthy); S2 failure
+ * still evaluates S3 (the walk is safe and more findings help repair).
+ * `pass` is false iff any gate FAILs; warn-level findings never fail (v0.3).
+ */
+import Ajv2020 from "ajv/dist/2020.js";
+import type { Contract, Surface } from "../contract.js";
+import { surfaceSchemaV0_1 } from "../surface-schema.js";
+import { type Finding, type GateReport, type LintReport } from "./findings.js";
+import { checkVocabulary } from "./vocabulary.js";
+import { evaluateRules } from "./rules.js";
+
+export { renderText, LEVEL_OF } from "./findings.js";
+export type { Finding, FindingLevel, FindingLocation, GateName, GateReport, GateStatus, LintReport } from "./findings.js";
+export { UnknownRuleTypeError } from "./rules.js";
+export { walkSurface } from "./walk.js";
+
+const ajv = new Ajv2020({ strict: false, allErrors: true });
+const validateSurfaceSchema = ajv.compile(surfaceSchemaV0_1 as unknown as Record<string, unknown>);
+
+export function lintSurface(surface: unknown, contract: Contract): LintReport {
+  const gates: GateReport[] = [];
+  let findings: Finding[] = [];
+
+  // S1 — generic surface schema.
+  const s1Ok = validateSurfaceSchema(surface) as boolean;
+  gates.push({
+    gate: "S1",
+    name: "surface-schema",
+    status: s1Ok ? "PASS" : "FAIL",
+    errors: s1Ok
+      ? undefined
+      : (validateSurfaceSchema.errors ?? []).map((e) => `${e.instancePath || "(root)"} ${e.message ?? ""}`.trim()),
+  });
+
+  if (!s1Ok) {
+    gates.push({ gate: "S2", name: "contract-vocabulary", status: "SKIPPED" });
+    gates.push({ gate: "S3", name: "governance", status: "SKIPPED" });
+    return summarize(gates, findings);
+  }
+
+  const typed = surface as Surface;
+
+  // S2 — contract vocabulary (a check on the artifact, whatever produced it).
+  const s2Errors = checkVocabulary(typed, contract);
+  gates.push({
+    gate: "S2",
+    name: "contract-vocabulary",
+    status: s2Errors.length === 0 ? "PASS" : "FAIL",
+    errors: s2Errors.length ? s2Errors : undefined,
+  });
+
+  // S3 — governance. Unknown rule types throw (CLI exit 4), never skip.
+  findings = evaluateRules(typed, contract);
+  gates.push({
+    gate: "S3",
+    name: "governance",
+    status: findings.some((f) => f.level === "error") ? "FAIL" : "PASS",
+  });
+
+  return summarize(gates, findings);
+}
+
+function summarize(gates: GateReport[], findings: Finding[]): LintReport {
+  const errorCount = findings.filter((f) => f.level === "error").length;
+  const warnCount = findings.filter((f) => f.level === "warn").length;
+  return {
+    gates,
+    findings,
+    errorCount,
+    warnCount,
+    pass: gates.every((g) => g.status !== "FAIL"),
+  };
+}