@sun-asterisk/sungen 3.1.2-beta.93 → 3.1.2-beta.98

package/dist/orchestrator/templates/specs-api.ts

@@ -0,0 +1,101 @@
+/* eslint-disable */
+/**
+ * Sungen API Driver — runtime helper (auto-generated into specs/api.ts).
+ *
+ * Runs a catalog-defined HTTP request and returns { status, ok, body, headers } — bound to a
+ * `{{name}}` variable by the `@api:<name>` annotation, asserted with `expect {{name.status}} …` /
+ * `{{name.body.<path>}}`. Base URL + auth come from a `kind: api` datasource in datasources.yaml,
+ * with `${VAR}` resolved from .env.qa / process.env — never inline.
+ *
+ * Safety: a datasource flagged `env: production` is refused unless SUNGEN_ALLOW_PROD=1.
+ * DO NOT EDIT — regenerated by `sungen generate`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface ApiDataSource {
+  kind?: string;
+  base_url?: string;
+  baseUrl?: string;
+  env?: string;
+  headers?: Record<string, string>;
+  timeout_ms?: number;
+}
+
+function loadEnvQa(): void {
+  for (const name of ['.env.qa', `.env.qa.${process.env.SUNGEN_ENV || ''}`]) {
+    const p = path.join(process.cwd(), name);
+    if (!name.endsWith('.') && fs.existsSync(p)) {
+      for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+        const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+        if (m && process.env[m[1]] === undefined) process.env[m[1]] = m[2].replace(/^["']|["']$/g, '');
+      }
+    }
+  }
+}
+
+function loadConfig(): Record<string, ApiDataSource> {
+  loadEnvQa();
+  const file = [path.join(process.cwd(), 'datasources.yaml'), path.join(process.cwd(), 'qa', 'datasources.yaml')].find((f) => fs.existsSync(f));
+  if (!file) throw new Error('API Driver: no datasources.yaml found (project root or qa/).');
+  const raw = fs.readFileSync(file, 'utf8').replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, k) => process.env[k] ?? '');
+  const { parse } = require('yaml');
+  const doc = parse(raw) || {};
+  return doc.datasources || {};
+}
+
+function substitute(text: string, params: Record<string, any>): string {
+  return text.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => encodeURIComponent(String(params[p] ?? '')));
+}
+
+class ApiClient {
+  private configs: Record<string, ApiDataSource> | null = null;
+
+  private cfg(name?: string): { key: string; conf: ApiDataSource } {
+    if (!this.configs) this.configs = loadConfig();
+    const key = name || Object.keys(this.configs).find((k) => (this.configs![k].kind || 'api') === 'api') || Object.keys(this.configs)[0];
+    const conf = this.configs[key];
+    if (!conf) throw new Error(`API Driver: datasource "${key}" not found in datasources.yaml`);
+    if (conf.env === 'production' && process.env.SUNGEN_ALLOW_PROD !== '1') {
+      throw new Error(`API Driver: datasource "${key}" is env: production — refused (set SUNGEN_ALLOW_PROD=1 to override).`);
+    }
+    return { key, conf };
+  }
+
+  /** Run a catalog request and return the response. `req` is embedded at compile time; `params` bind at runtime. */
+  async call(
+    label: string,
+    req: { method: string; path: string; body?: unknown; datasource?: string },
+    params: Record<string, any> = {},
+  ): Promise<{ status: number; ok: boolean; body: any; headers: Record<string, string> }> {
+    const { conf } = this.cfg(req.datasource);
+    const base = (conf.base_url || conf.baseUrl || '').replace(/\/$/, '');
+    if (!base) throw new Error(`API Driver: ${label} — datasource has no base_url (set it in .env.qa).`);
+    const url = base + substitute(req.path, params);
+
+    let body: string | undefined;
+    const headers: Record<string, string> = { ...(conf.headers || {}) };
+    if (req.body !== undefined && req.body !== null) {
+      const resolved = JSON.parse(JSON.stringify(req.body).replace(/":([A-Za-z_][A-Za-z0-9_]*)"/g, (_m, p) => JSON.stringify(params[p] ?? null)));
+      body = JSON.stringify(resolved);
+      if (!headers['content-type'] && !headers['Content-Type']) headers['content-type'] = 'application/json';
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), conf.timeout_ms ?? 15000);
+    let res: Response;
+    try {
+      res = await fetch(url, { method: req.method, headers, body, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let parsed: any = text;
+    try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
+    const outHeaders: Record<string, string> = {};
+    res.headers.forEach((v, k) => { outHeaders[k] = v; });
+    return { status: res.status, ok: res.ok, body: parsed, headers: outHeaders };
+  }
+}
+
+export const api = new ApiClient();

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.1.2-beta.93",
+  "version": "3.1.2-beta.98",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "bin": {
     "sungen": "./bin/sungen.js"
   },
   "scripts": {
-    "build": "tsc && npm run copy-templates",
+    "build": "rm -rf dist && tsc && npm run copy-templates",
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
-    "build:dashboard": "cd dashboard && npm install --silent && npm run build && cd .. && cp dashboard/dist/index.html src/dashboard/templates/index.html",
+    "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
@@ -33,6 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@sungen/driver-ui": "3.1.2-beta.98",
     "@anthropic-ai/sdk": "^0.71.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",
@@ -52,37 +53,13 @@
     "yaml": "^2.8.2",
     "zod": "^4.1.13"
   },
-  "devDependencies": {
-    "@playwright/test": "^1.57.0",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.0",
-    "@types/jsdom": "^27.0.0",
-    "@types/node": "^20",
-    "jsdom": "^27.3.0",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "typescript": "^5"
-  },
   "peerDependencies": {
     "@playwright/test": "^1.57.0"
   },
-  "overrides": {
-    "brace-expansion": "^5.0.6",
-    "uuid": "^11.1.1",
-    "tmp": "^0.2.6",
-    "esbuild": "^0.28.1"
-  },
-  "resolutions": {
-    "brace-expansion": "^5.0.6",
-    "uuid": "^11.1.1",
-    "tmp": "^0.2.6",
-    "esbuild": "^0.28.1"
-  },
   "files": [
     "dist",
     "bin",
     "src",
-    "docs/orchestration-spec.md",
     "README.md",
     "LICENSE"
   ]

package/src/capabilities/builtins.ts

@@ -0,0 +1,85 @@
+/**
+ * In-core capability registrations (Capability SPI).
+ *
+ * `ui` has moved to `@sungen/driver-ui` (R5.4); `db` and `api` still register from here via
+ * `LOCAL_DRIVERS` (they relocate in R5.5/R5.6), and `core` (the generic expect/lint/verification
+ * layer) always stays in core. Discovery (`discover.ts`) loads the external driver(s) first, then
+ * these, then `core` — preserving the historical pattern composition order, so compiled output is
+ * byte-identical (golden + audit snapshots are the proof).
+ */
+import type { CapabilityRegistry } from './registry';
+import type { Sensor, AdvisoryScanInput, GateInput } from './sensor';
+import { lintDataDriven } from '../harness/data-driven-lint';
+import { resolveQuery, lintCatalog } from '../harness/query-catalog';
+import { expectPatterns } from '../generators/test-generator/patterns/expect-patterns';
+
+/** Advisory @cases/@query lint, exposed through the Sensor SPI (generate-time). */
+const dataDrivenLintSensor: Sensor<AdvisoryScanInput> = {
+  id: 'data-driven-lint',
+  capability: 'core',
+  kind: 'advisory',
+  run: ({ dir, cwd }) =>
+    lintDataDriven(dir, cwd).map((w) => ({
+      sensorId: 'data-driven-lint',
+      capability: 'core',
+      scenario: w.scenario,
+      message: w.message,
+      severity: 'warn' as const,
+    })),
+};
+
+/**
+ * Generic `verification` gate sensor: every referenced named query (`@query`) must resolve in its
+ * catalog, and the catalog must lint clean. An unresolved/invalid reference is a gate-level error.
+ * (On a project with no `@query` refs it yields nothing.) `query-catalog` lives in core's harness —
+ * shared with the data-driven advisory lint. The `@api` counterpart now lives in
+ * `@sungen/driver-api`'s `api-verification` gate sensor. Message prefix unchanged → audit byte-identical.
+ */
+const verificationGateSensor: Sensor<GateInput> = {
+  id: 'verification',
+  capability: 'core',
+  kind: 'gate',
+  run: ({ screenName, scenarios, cwd }) => {
+    const findings = [] as ReturnType<Sensor['run']>;
+    const fail = (msg: string) => findings.push({ sensorId: 'verification', capability: 'core', message: `VERIFICATION-FAIL: ${msg}`, severity: 'error' });
+
+    const queryRefs = new Set<string>();
+    for (const s of scenarios) for (const r of s.queryRefs ?? []) queryRefs.add(r);
+    for (const name of queryRefs) {
+      try { resolveQuery(name, screenName, cwd); } catch (e: any) { fail(e?.message || `query "${name}" does not resolve`); }
+    }
+    if (queryRefs.size) {
+      try { for (const err of lintCatalog(screenName, null, cwd).errors) fail(err); } catch { /* no catalog */ }
+    }
+    return findings;
+  },
+};
+
+/**
+ * core — generic, capability-agnostic steps (data-vs-data `expect`) + the advisory @cases/@query
+ * lint and the gate-level `verification` sensor. Stays in core (not a driver) — the always-present
+ * generic layer. All three real capabilities (ui/db/api) now ship as `@sungen/driver-*` packages.
+ */
+export function registerCoreCapability(registry: CapabilityRegistry): void {
+  registry.register({
+    id: 'core',
+    patterns: [...expectPatterns],
+    sensors: [dataDrivenLintSensor, verificationGateSensor],
+  });
+}
+
+/**
+ * In-core driver manifest — now empty: `ui`, `db`, and `api` all ship as `@sungen/driver-*` packages
+ * loaded by discovery (`discover.ts`). Kept (empty) as the seam for any future in-core capability;
+ * `core` itself registers separately via `registerCoreCapability`.
+ */
+export const LOCAL_DRIVERS: ReadonlyArray<{ capability: string; register: (r: CapabilityRegistry) => void }> = [];
+
+/**
+ * @deprecated Use `discoverAndRegisterCapabilities()` from `./discover`. Kept as a thin alias so
+ * existing call-sites/tests don't break during R5; removed once everything routes through discovery.
+ */
+export function registerBuiltinCapabilities(): void {
+  // Lazy import avoids a cycle (discover imports builtins).
+  require('./discover').discoverAndRegisterCapabilities();
+}

package/src/capabilities/context-router.ts

@@ -0,0 +1,66 @@
+/**
+ * ContextRouter (Capability SPI, R1 — skeleton).
+ *
+ * The overload guard: for each unit of work it decides the minimal slice of Context + the relevant
+ * capabilities + the gate to load, so a project with many drivers doesn't gather everything for
+ * every artifact (cost scales by *target*, not *repo × drivers*). See
+ * `docs/spec/sungen_capability_spi_spec.md` §5.
+ *
+ * R1 scope (skeleton, deterministic, not yet enforced in the pipeline): it computes the routing
+ * plan — which capabilities apply (the default/implicit one + any whose annotation tags appear),
+ * and which sensors gate the task. Scope-trimming/token-budget enforcement is wired in a later step;
+ * for now `scope.budget` is a placeholder (null = unbounded) and the plan is advisory.
+ */
+import { capabilityRegistry } from './registry';
+
+export interface RouteTask {
+  /** What is being worked on now. */
+  target: { kind: string; id: string };
+  /** What artifact is being produced/checked: 'feature' | 'scenario' | 'selectors' | 'apis.yaml' | … */
+  artifact: string;
+  /** Capability tags present on the target (e.g. ['@query'], ['@api'], ['@cases']). */
+  tags?: string[];
+}
+
+export interface RoutePlan {
+  /** Applicable capability ids: the default/implicit one + any whose annotations match the tags. */
+  capabilities: string[];
+  /** Gate sensors to run for this task (ids). */
+  gateSensorIds: string[];
+  /** Advisory sensors to run for this task (ids). */
+  advisorySensorIds: string[];
+  /** Scope: the target slice + a token/context budget (null = unbounded for now). */
+  scope: { target: RouteTask['target']; budget: number | null };
+}
+
+class ContextRouter {
+  /** Which capabilities a set of tags activates: the default capability + any owning a present tag. */
+  capabilitiesFor(tags: string[] = []): string[] {
+    const ids = new Set<string>();
+    const def = capabilityRegistry.defaultCapabilityId();
+    if (def) ids.add(def);
+    for (const cap of capabilityRegistry.all()) {
+      if ((cap.annotations ?? []).some((a) => tags.includes(a))) ids.add(cap.id);
+    }
+    return [...ids];
+  }
+
+  /** Compute the routing plan for a task (deterministic). */
+  route(task: RouteTask): RoutePlan {
+    const capabilities = this.capabilitiesFor(task.tags ?? []);
+    // Generic sensors (no capability, or the always-on `core`) run regardless of the task's tags;
+    // capability-specific sensors run only when their capability is in scope.
+    const inScope = (capId?: string) => capId == null || capId === 'core' || capabilities.includes(capId);
+    const gateSensorIds = capabilityRegistry.sensors('gate').filter((s) => inScope(s.capability)).map((s) => s.id);
+    const advisorySensorIds = capabilityRegistry.sensors('advisory').filter((s) => inScope(s.capability)).map((s) => s.id);
+    return {
+      capabilities,
+      gateSensorIds,
+      advisorySensorIds,
+      scope: { target: task.target, budget: null },
+    };
+  }
+}
+
+/** Process-wide singleton. */
+export const contextRouter = new ContextRouter();

package/src/capabilities/context.ts

@@ -0,0 +1,46 @@
+/**
+ * Orchestration phase-hook SPIs (Capability SPI, R1 — phase hooks).
+ *
+ * The kernel owns the pipeline (Plan → Discover → Contextualize → Generate → Gate → Repair →
+ * Deliver); a capability fills the domain-specific phases via these hooks:
+ *  - `DiscoveryProvider` — sources → a slice of the normalized `Context`.
+ *  - `ContextMapper`     — `Context` → generation units + the capability's MODES
+ *                          (ui: screen|flow; api: matrix|flow|async; db: query-catalog).
+ *
+ * R1 scope: these are **declared** (the contract) and attachable to a CapabilityDescriptor, but
+ * the kernel does not consume them yet — the pipeline still runs as before. R2 (driver-ui) is the
+ * first conformer that implements them; the orchestration is rewired to call them then.
+ * See `docs/spec/sungen_capability_spi_spec.md` §3–§6 and `sungen_ui_driver_spec.md`.
+ */
+
+/** Normalized, capability-tagged discovery output. Lazy/sliced — never materialized whole. */
+export interface Context {
+  target: { kind: string; id: string; capability?: string };
+  /** Lazy source handles (spec/viewpoint/openapi/routes/schema/liveSnapshot/figma/…). */
+  sources: Record<string, unknown>;
+  /** Capability-specific normalized facts (ui: elements/states/pageType; api: endpoints; db: tables). */
+  facts: Record<string, unknown>;
+  /** For run-time-connected capabilities (api/db): reachability probe result. */
+  connectivity?: { reachable: boolean; baseUrl?: string; probedAt?: string };
+}
+
+/** One unit of generation work the kernel will drive through Generate → Gate → Repair. */
+export interface GenerationUnit {
+  /** Capability-defined mode: 'screen' | 'flow' | 'matrix' | 'async' | 'query-catalog' | … */
+  mode: string;
+  /** The slice of Context this unit covers (a screen, an endpoint group, a query set, …). */
+  targetSlice: unknown;
+  /** Band weight hint (source-aware) — the kernel supplies the band targets. */
+  weight?: number;
+}
+
+export interface DiscoveryProvider {
+  appliesTo(target: Context['target']): boolean;
+  /** Produce this capability's slice of the Context for the given target + requested scope. */
+  discover(target: Context['target'], scope: unknown): Promise<Partial<Context>>;
+}
+
+export interface ContextMapper {
+  /** Turn the Context into generation units (+ modes), honouring the kernel's band targets. */
+  decompose(ctx: Context, bands?: Record<string, number>): GenerationUnit[];
+}

package/src/capabilities/discover.ts

@@ -0,0 +1,42 @@
+/**
+ * Capability discovery (R5 packaging seam).
+ *
+ * Core registers capabilities without importing any driver package statically. External
+ * `@sungen/driver-*` packages are loaded at runtime via their `sungenDriver.register` entry point;
+ * the capabilities still in core (`db`, `api`) register from `LOCAL_DRIVERS`; the generic `core`
+ * capability registers last. Idempotent (guards on `registry.isPopulated()`).
+ *
+ * Ordering is deterministic and behaviour-preserving: external drivers (currently `@sungen/driver-ui`)
+ * load first, then `LOCAL_DRIVERS` (db → api), then `core` — i.e. the historical ui → db → api → core
+ * composition order, so pattern composition / compiled output is byte-identical.
+ *
+ * A driver that isn't installed is simply skipped (capabilities are opt-in). Errors thrown *inside* a
+ * present driver propagate — only a genuinely absent package is swallowed (resolve-then-require).
+ */
+import { capabilityRegistry } from './registry';
+import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
+
+/**
+ * Driver packages relocated out of core, loaded before the in-core `LOCAL_DRIVERS`. As `db`/`api`
+ * move to their packages (R5.5/R5.6) they join this list and leave `LOCAL_DRIVERS`; eventually this
+ * becomes a scan of installed `@sungen/driver-*` packages (R5.7).
+ */
+const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api'];
+
+function loadExternalDriver(name: string): void {
+  try {
+    require.resolve(name);
+  } catch {
+    return; // not installed — capabilities are opt-in, so skip silently
+  }
+  const mod = require(name); // present: let any error thrown inside the driver propagate (don't mask)
+  const register: ((r: typeof capabilityRegistry) => void) | undefined = mod?.sungenDriver?.register ?? mod?.register;
+  if (typeof register === 'function') register(capabilityRegistry);
+}
+
+export function discoverAndRegisterCapabilities(): void {
+  if (capabilityRegistry.isPopulated()) return;
+  for (const name of EXTERNAL_DRIVERS) loadExternalDriver(name); // ui (external) — first, default capability
+  for (const driver of LOCAL_DRIVERS) driver.register(capabilityRegistry); // db, api (in-core for now)
+  registerCoreCapability(capabilityRegistry); // generic layer, always present, registered last
+}

package/src/capabilities/registry.ts

@@ -0,0 +1,111 @@
+/**
+ * Capability registry — the extension seam for the microkernel (Capability SPI, R1).
+ *
+ * Replaces hardcoded `this.patterns.push(...)` wiring with **registration**: each capability
+ * (ui · db · api · …) declares what it contributes; the kernel composes it. This is the
+ * "shared framework, pull in what you use" mechanism (`docs/spec/sungen_capability_spi_spec.md`).
+ *
+ * R1 scope (behaviour-preserving): only the **patterns** slice is wired through here — the set of
+ * registered patterns is identical to the old hardcoded list, so compiled output is unchanged
+ * (golden + audit snapshots are the contract). The remaining SPI slices (discovery, contextMapper,
+ * sensors, adapter, viewpoints, runtimeHelpers) are declared on the descriptor for the upcoming
+ * steps but are not consumed yet.
+ */
+import type { StepPattern } from '../generators/test-generator/patterns/types';
+import type { Sensor } from './sensor';
+import type { DiscoveryProvider, ContextMapper } from './context';
+
+export interface CapabilityDescriptor {
+  /** Stable id: 'ui' | 'db' | 'api' | 'core' | … */
+  id: string;
+  /** The implicit/default capability (a scenario with no capability tag). UI sets this. */
+  default?: boolean;
+  /** Annotation tags this capability owns (e.g. ['@query'], ['@api','@hybrid']). */
+  annotations?: string[];
+  /** Step patterns this capability contributes to the compiler. */
+  patterns?: StepPattern[];
+  /** Harness sensors this capability contributes (advisory and/or gate). */
+  sensors?: Sensor[];
+  /** Orchestration phase hooks — declared in R1, consumed by the pipeline from R2 onward. */
+  discovery?: DiscoveryProvider;     // sources → Context slice
+  contextMapper?: ContextMapper;     // Context → generation units + modes
+  /** Provider for this capability's viewpoint catalog (UI: the 17-pattern universal catalog). */
+  viewpoints?: () => unknown;
+  /**
+   * Score-bearing gate computation owned by this capability (UI: viewpoint coverage + assertion
+   * depth). The audit engine calls it and assembles the score from the result. Typed generically
+   * so the registry stays decoupled from harness internals; the caller knows the concrete shape.
+   */
+  gateProvider?: (input: unknown) => unknown;
+  /** Runtime helper file(s) this capability emits into specs/ when it is active for a feature
+   *  (db → specs/db.ts). Emitted via the same sync-when-changed mechanism. */
+  runtimeHelpers?: Array<{ file: string; template: string }>;
+  /** Optional step detector: the capability is "active" for a feature if any step matches —
+   *  for steps that carry no annotation tag (db's declarative `User see [t] row where …`). */
+  detectsStep?: (stepText: string) => boolean;
+  /**
+   * Precondition codegen for this capability's annotations on a scenario (db's `@query:<name>`
+   * → `testData.bind(name, await db.fetchQuery(...))`). Returns raw statements (the compiler
+   * indents) + `boundVars` (the `{{name}}` variables it binds, so the compiler registers them as
+   * runtime-resolved). Keeps `@query` codegen owned by `db`, not hardcoded in the compiler.
+   */
+  preconditionCodegen?: (input: { tags: string[]; screenName: string; cwd: string }) =>
+    Array<{ comment?: string; code: string; boundVars?: string[] }>;
+
+  /**
+   * CLI commands this capability contributes. The CLI calls each with the commander `program`
+   * (typed generically so the registry stays decoupled from commander; the driver knows the shape).
+   * Lets a driver own its authoring commands (api → `sungen api import`) instead of hardcoding them
+   * in core's CLI. Invoked once, after discovery, in `src/cli/index.ts`.
+   */
+  cliCommands?: Array<(program: unknown) => void>;
+
+  // --- Declared for later R-steps; not consumed yet (kept here so the SPI shape is visible). ---
+  // adapter?: string;                  // codegen adapter id (existing adapterRegistry)
+}
+
+export class CapabilityRegistry {
+  private caps = new Map<string, CapabilityDescriptor>();
+
+  /** Register (or replace, by id) a capability descriptor. Idempotent by id. */
+  register(descriptor: CapabilityDescriptor): void {
+    this.caps.set(descriptor.id, descriptor);
+  }
+
+  get(id: string): CapabilityDescriptor | undefined {
+    return this.caps.get(id);
+  }
+
+  /** True once any capability is registered — discovery guards on this (replaces the builtins boolean). */
+  isPopulated(): boolean {
+    return this.caps.size > 0;
+  }
+
+  all(): CapabilityDescriptor[] {
+    return [...this.caps.values()];
+  }
+
+  /** The id of the implicit/default capability (UI), if registered. */
+  defaultCapabilityId(): string | undefined {
+    return this.all().find((c) => c.default)?.id;
+  }
+
+  /** All step patterns contributed by registered capabilities (composition order = registration order). */
+  patterns(): StepPattern[] {
+    return this.all().flatMap((c) => c.patterns ?? []);
+  }
+
+  /** All registered sensors, optionally filtered by kind ('advisory' | 'gate'). */
+  sensors(kind?: Sensor['kind']): Sensor[] {
+    const all = this.all().flatMap((c) => c.sensors ?? []);
+    return kind ? all.filter((s) => s.kind === kind) : all;
+  }
+
+  /** Test seam: drop all registrations. */
+  _reset(): void {
+    this.caps.clear();
+  }
+}
+
+/** Process-wide singleton (mirrors `adapterRegistry`). */
+export const capabilityRegistry = new CapabilityRegistry();

package/src/capabilities/sensor.ts

@@ -0,0 +1,47 @@
+/**
+ * Harness Sensor SPI (Capability SPI, R1 — Sensor step).
+ *
+ * A sensor is a deterministic harness check a capability contributes. The kernel collects all
+ * registered sensors and runs them; findings merge into the harness output. Two kinds:
+ *  - `advisory` — surfaced as warnings (e.g. at `sungen generate`), never blocks.
+ *  - `gate`     — feeds the audit scorecard / pass-fail (migrated from the hardcoded `audit.ts`
+ *                 calls in the next sub-step; gate sensors carry an intent-aware threshold).
+ *
+ * Generic over the input so the same registry holds both generate-time advisory sensors
+ * (which scan a screen/flow dir) and audit-time gate sensors (which read parsed scenarios) —
+ * each sensor declares the input it consumes; callers filter by `kind` and pass the right input.
+ */
+export interface SensorFinding {
+  sensorId: string;
+  capability?: string;
+  scenario?: string;
+  message: string;
+  severity?: 'info' | 'warn' | 'error';
+}
+
+export interface Sensor<I = unknown> {
+  id: string;
+  capability?: string;
+  kind: 'gate' | 'advisory';
+  run(input: I): SensorFinding[];
+}
+
+/** Input for generate-time advisory sensors that scan a screen/flow directory. */
+export interface AdvisoryScanInput {
+  dir: string;
+  cwd: string;
+}
+
+/**
+ * Input for audit-time gate sensors. Intentionally minimal/structural (not the full ScenarioInfo
+ * type) so `src/capabilities` doesn't depend on harness internals — the audit caller passes the
+ * parsed scenarios it already has.
+ */
+export interface GateInput {
+  screenName: string;
+  cwd: string;
+  featureText: string;
+  scenarios: Array<{ name: string; queryRefs?: string[]; apiRefs?: string[] }>;
+  /** UI: universal-viewpoint theme gaps the coverage gate found (generic string list). */
+  universalGaps?: string[];
+}

package/src/cli/commands/generate.ts

@@ -4,7 +4,8 @@ import * as fs from 'fs';
 import { CodeGenerator } from '../../generators/test-generator/code-generator';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 import { scanTestDataSecrets } from '../../harness/secret-scan';
-import { lintDataDriven } from '../../harness/data-driven-lint';
+import { capabilityRegistry } from '../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
 
 /**
@@ -183,8 +184,11 @@ export function registerGenerateCommand(program: Command): void {
           console.log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.`);
         }
 
-        // Data-driven lint (@cases / @query) — advisory, never blocks generation.
-        const ddWarnings = scanDirs.flatMap((d) => lintDataDriven(d, cwd));
+        // Advisory harness sensors (e.g. @cases/@query lint) — run via the Capability SPI,
+        // never block generation. Each capability registers its own; the kernel just runs them.
+        discoverAndRegisterCapabilities();
+        const advisorySensors = capabilityRegistry.sensors('advisory');
+        const ddWarnings = scanDirs.flatMap((d) => advisorySensors.flatMap((s) => s.run({ dir: d, cwd })));
         if (ddWarnings.length) {
           console.log(`\n⚠️  Data-driven lint (@cases / @query) — review:`);
           for (const w of ddWarnings.slice(0, 20)) console.log(`   ${w.scenario ? w.scenario + ': ' : ''}${w.message}`);

package/src/cli/index.ts

@@ -26,6 +26,8 @@ import { registerChallengeCommand } from './commands/challenge';
 import { registerBlindspotCommand } from './commands/blindspot';
 import { registerCapabilityCommand } from './commands/capability';
 import { registerFlowCheckCommand } from './commands/flow-check';
+import { capabilityRegistry } from '../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 
 // Read version from package.json so `--version` never drifts from the released version.
 const { version } = require('../../package.json') as { version: string };
@@ -42,7 +44,7 @@ async function main() {
   program
     .option('-v, --verbose', 'Enable verbose logging');
 
-  // Register commands (9)
+  // Register commands
   registerInitCommand(program);
   registerAddCommand(program);
   registerGenerateCommand(program);
@@ -65,6 +67,13 @@ async function main() {
   registerIngestCommand(program);
   registerEvalCommand(program);
 
+  // Capability-contributed CLI commands (Capability SPI): drivers own their authoring commands
+  // (e.g. @sungen/driver-api → `sungen api import`). Discover, then register each.
+  discoverAndRegisterCapabilities();
+  for (const cap of capabilityRegistry.all()) {
+    for (const registerCommand of cap.cliCommands ?? []) registerCommand(program);
+  }
+
   await program.parseAsync(process.argv);
 }
 

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -64,7 +64,7 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string;
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;

package/src/generators/test-generator/adapters/playwright/playwright-adapter.ts

@@ -26,7 +26,7 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {
     return this.templateEngine.renderImports(options);
   }