@sun-asterisk/sungen 3.1.2 → 3.2.0-beta.141

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.1.2",
+  "version": "3.2.0-beta.141",
   "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.2.0-beta.141",
     "@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,65 @@
+/**
+ * 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[];
+}
+
+/**
+ * Repair phase hook — a capability's deterministic fix catalog. Each rule matches a finding (audit
+ * gap) or a runtime failure message and proposes a concrete fix. `sungen repair` gathers the
+ * unit-capability's rules and turns the findings/failures into an actionable plan; the AI repair
+ * loop and a human get the same proposals. Drivers/projects extend the catalog by adding rules.
+ */
+export interface RepairRule {
+  /** Stable id, e.g. 'api-error' | 'api-auth'. */
+  id: string;
+  /** Matches a finding or failure message. */
+  match: RegExp;
+  /** The concrete repair instruction to apply. */
+  fix: string;
+}
+
+export interface RepairProvider {
+  rules: RepairRule[];
+}

package/src/capabilities/discover.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { createRequire } from 'module';
+import * as path from 'path';
+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 {
+  // Resolve from the user's PROJECT first, then from core's own location. Opt-in drivers
+  // (`sungen capability add db|api`) install into the PROJECT's node_modules — a globally-installed
+  // core (`npm i -g`) wouldn't see them via a core-anchored `require`. The bundled @sungen/driver-ui
+  // is a core dependency (co-located with core), so the second anchor finds it.
+  for (const anchor of [path.join(process.cwd(), 'package.json'), __filename]) {
+    let req: NodeRequire;
+    try { req = createRequire(anchor); } catch { continue; }
+    let resolved: string;
+    try { resolved = req.resolve(name); } catch { continue; } // not installed at this anchor → try next
+    try {
+      const mod = req(resolved);
+      const register: ((r: typeof capabilityRegistry) => void) | undefined = mod?.sungenDriver?.register ?? mod?.register;
+      if (typeof register === 'function') register(capabilityRegistry);
+    } catch (e) {
+      // A present-but-BROKEN driver (e.g. a stale/incompatible leftover whose own core dep doesn't
+      // resolve) must never crash the whole CLI — `sungen --version`, `capability remove`, etc. must
+      // still work. Warn + skip so the user can recover.
+      console.warn(
+        `⚠ sungen: capability driver "${name}" is installed but failed to load — skipping.\n` +
+        `  ${(e as Error)?.message || e}\n` +
+        `  Fix: reinstall it (\`sungen capability add ${name.replace(/^@sungen\/driver-/, '')}\`) or remove it.`,
+      );
+    }
+    return; // found at this anchor (loaded or warned) — don't fall through to other anchors
+  }
+  // not installed at any anchor — capabilities are opt-in, so skip silently
+}
+
+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,113 @@
+/**
+ * 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, RepairProvider } 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
+  /** Repair phase: the capability's deterministic fix catalog (audit/runtime finding → fix). */
+  repair?: RepairProvider;
+  /** 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[]; casesDataset?: string; stepsText?: string; manual?: boolean }>;
+  /** UI: universal-viewpoint theme gaps the coverage gate found (generic string list). */
+  universalGaps?: string[];
+}

package/src/cli/commands/audit.ts

@@ -2,12 +2,16 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { runAudit, AuditReport } from '../../harness/audit';
+import { reportSlug } from '../../harness/unit-paths';
 
 function findScreenDir(name: string): string | null {
-  const screen = path.join(process.cwd(), 'qa', 'screens', name);
-  if (fs.existsSync(screen)) return screen;
-  const flow = path.join(process.cwd(), 'qa', 'flows', name);
-  if (fs.existsSync(flow)) return flow;
+  // `name` may be a bare screen/flow/area, or an api unit id (`api/<area>`, `api/flows/<flow>`).
+  const candidates = [
+    path.join(process.cwd(), 'qa', 'screens', name),
+    path.join(process.cwd(), 'qa', 'flows', name),
+    path.join(process.cwd(), 'qa', 'api', name),         // qa/api/<area> or qa/api/flows/<flow>
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
   return null;
 }
 
@@ -88,20 +92,22 @@ export function registerAuditCommand(program: Command): void {
     .command('audit')
     .description('Harness: measure test-design quality (viewpoint gate, depth, balance, duplicates, traceability)')
     .option('-s, --screen <name>', 'Screen or flow name to audit')
+    .option('--api <name>', 'API-first area or api flow to audit (e.g. orders, flows/signup)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--json', 'Output the raw JSON report')
     .action((options) => {
       try {
-        const name = options.screen;
-        if (!name) throw new Error('Provide --screen <name>');
+        const name = options.screen || options.api || options.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
         const dir = findScreenDir(name);
-        if (!dir) throw new Error(`Screen/flow not found: qa/screens/${name} or qa/flows/${name}`);
+        if (!dir) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
         const report = runAudit(dir, name);
 
-        // Persist report under .sungen/reports/
+        // Persist report under .sungen/reports/ (flat slug: api flow `flows/x` → `flows-x-audit.json`).
         const outDir = path.join(process.cwd(), '.sungen', 'reports');
         fs.mkdirSync(outDir, { recursive: true });
-        const outPath = path.join(outDir, `${name}-audit.json`);
+        const outPath = path.join(outDir, `${reportSlug(name)}-audit.json`);
         fs.writeFileSync(outPath, JSON.stringify(report, null, 2), 'utf-8');
 
         if (options.json) {

package/src/cli/commands/capability.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import { spawnSync } from 'child_process';
+import { createRequire } from 'module';
 import * as fs from 'fs';
 import * as path from 'path';
 import {
@@ -8,6 +9,42 @@ import {
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 
+/** The running CLI's (core) version — opt-in drivers install in lockstep with it (not `@latest`). */
+function coreVersion(): string {
+  try { return require('../../../package.json').version || 'latest'; } catch { return 'latest'; }
+}
+
+/**
+ * Verify a capability driver (db/api/…) installed into the PROJECT exposes the capability SPI entry
+ * (`sungenDriver.register`). Resolved from the project's node_modules so it works with a globally
+ * installed core. Capability drivers are NOT codegen adapters — don't route them through loadDriver.
+ */
+function verifyCapabilityDriver(pkg: string, cwd: string): void {
+  const req = createRequire(path.join(cwd, 'package.json'));
+  // 1) Installed? (resolve only — distinguishes "not installed" from "installed but broken")
+  try {
+    req.resolve(pkg);
+  } catch {
+    throw new Error(`${pkg} is not installed in this project — run \`npm install -D ${pkg}\` here (a package.json must exist in this directory).`);
+  }
+  // 2) Loadable? Surface the REAL error — a failure here is almost always a stale/wrong
+  //    @sun-asterisk/sungen on the module path (e.g. leftover node_modules), NOT a missing driver.
+  let mod: any;
+  try {
+    mod = req(pkg);
+  } catch (e: any) {
+    throw new Error(
+      `${pkg} is installed but failed to load:\n  ${e?.message || e}\n` +
+      '  This usually means a stale @sun-asterisk/sungen is on the module path. Run in a clean,\n' +
+      '  dedicated project directory and remove stray installs (e.g. rm -rf ~/node_modules).',
+    );
+  }
+  const register = mod?.sungenDriver?.register ?? mod?.register;
+  if (typeof register !== 'function') {
+    throw new Error(`${pkg} is installed but is not a sungen capability driver (missing sungenDriver.register).`);
+  }
+}
+
 function findScreenDir(name: string): string | null {
   const s = path.join(process.cwd(), 'qa', 'screens', name);
   if (fs.existsSync(s)) return s;
@@ -111,16 +148,27 @@ export function registerCapabilityCommand(program: Command): void {
         const bundled = adapterRegistry.hasAdapter(adapterName); // e.g. `web` is bundled in Phase 2a
 
         if (!bundled && !o.skipInstall) {
-          console.log(`📦 Installing ${meta.package} (dev dependency)...`);
-          const r = spawnSync('npm', ['install', '-D', meta.package], { stdio: 'inherit', shell: true });
-          if (r.status !== 0) throw new Error(`npm install -D ${meta.package} failed.`);
+          // Pin the driver to the RUNNING core's exact version (lockstep). Without this, plain
+          // `npm install @sungen/driver-x` resolves the package's `latest` dist-tag — which on a
+          // beta channel can lag (e.g. a prerelease first-published-as-latest), pulling a driver
+          // whose core dep resolves to the wrong @sun-asterisk/sungen and fails to load.
+          const spec = `${meta.package}@${coreVersion()}`;
+          console.log(`📦 Installing ${spec} (dev dependency)...`);
+          const r = spawnSync('npm', ['install', '-D', spec], { stdio: 'inherit', shell: true });
+          if (r.status !== 0) throw new Error(`npm install -D ${spec} failed.`);
         } else if (bundled) {
           console.log(`✓ ${driver} is built-in (no install needed).`);
         }
 
-        // Verify it can load (skip for bundled — already registered).
+        // Verify it loaded (skip for bundled — already registered). Two driver shapes:
+        //  - platform driver (web/mobile): a codegen adapter, loaded via the adapter registry (mod.activate)
+        //  - capability driver (db/api/…): a capability-SPI package (mod.sungenDriver.register) — NOT an adapter
         if (!bundled) {
-          adapterRegistry.loadDriver(adapterName, meta.package, cwd); // throws if not loadable
+          if (meta.kind === 'platform') {
+            adapterRegistry.loadDriver(adapterName, meta.package, cwd); // throws if not loadable
+          } else {
+            verifyCapabilityDriver(meta.package, cwd); // capability SPI entry, resolved from the project
+          }
         }
 
         const profile = readCapabilities(cwd);