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

package/src/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -6,6 +6,9 @@ import { TestDataLoader } from '{{basePath}}/test-data';
 {{#if needsDb}}
 import { db } from '{{basePath}}/db';
 {{/if}}
+{{#if needsApi}}
+import { api } from '{{basePath}}/api';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten

package/src/generators/test-generator/code-generator.ts

@@ -4,8 +4,8 @@ import { ParsedFeature, ParsedScenario, ParsedStep } from '../gherkin-parser';
 import { StepMapper } from './step-mapper';
 import { TestGeneratorAdapter, adapterRegistry } from './adapters';
 import { transformToRuntimeData } from './utils/runtime-data-transformer';
-import { isDbStep } from './patterns/database-patterns';
-import { resolveQuery, compileQuery } from '../../harness/query-catalog';
+import { capabilityRegistry } from '../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
@@ -240,11 +240,17 @@ export class CodeGenerator {
     const hasCleanupTags = (feature.tags || []).some(t => t.startsWith('@cleanup:'));
     const needsCleanupImport = !isParallelFeature && hasCleanupTags;
 
-    // Data Driver: if any step verifies DB state, import the `db` helper + emit specs/db.ts
-    const needsDb = this.featureUsesDb(feature);
-    if (needsDb) this.ensureDbFile(outputDir);
+    // Active capabilities for this feature (registry-driven): the default UI + any whose annotation
+    // tags appear (@query) or whose detectsStep matches (declarative DB steps). Each active
+    // capability emits its declared runtime helpers (db → specs/db.ts).
+    const activeCapabilityIds = this.activeCapabilityIds(feature);
+    const needsDb = activeCapabilityIds.includes('db');
+    const needsApi = activeCapabilityIds.includes('api');
+    for (const id of activeCapabilityIds) {
+      for (const h of capabilityRegistry.get(id)?.runtimeHelpers ?? []) this.syncGeneratedHelper(outputDir, h.file, h.template);
+    }
 
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb });
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi });
 
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
@@ -300,62 +306,40 @@ export class CodeGenerator {
   /**
    * Ensure specs/base.ts exists in the output directory
    */
-  /** True when any step (background or scenario) in the feature is a DB-verification step. */
-  private featureUsesDb(feature: ParsedFeature): boolean {
+  /**
+   * Capabilities active for a feature (registry-driven): the default (UI) capability, plus any
+   * whose annotation tags appear on a scenario (e.g. `@query` → db) or whose `detectsStep`
+   * matches a step (db's declarative `User see [table] row where …`). Drives runtime-helper
+   * emission + the `db` import — replaces the hardcoded `featureUsesDb` check (R4).
+   */
+  private activeCapabilityIds(feature: ParsedFeature): string[] {
+    discoverAndRegisterCapabilities();
     const steps: ParsedStep[] = [];
     if (feature.background?.steps) steps.push(...feature.background.steps);
     for (const sc of feature.scenarios || []) if (sc.steps) steps.push(...sc.steps);
-    if (steps.some((s) => s && typeof s.text === 'string' && isDbStep(s.text))) return true;
-    // A scenario may carry only a @query:<name> post-condition tag (no DB step in its body).
-    return (feature.scenarios || []).some((sc) => (sc.tags || []).some((t) => t.startsWith('@query:')));
+    const scenarioTags = (feature.scenarios || []).flatMap((sc) => sc.tags || []);
+    const ids = new Set<string>();
+    const def = capabilityRegistry.defaultCapabilityId();
+    if (def) ids.add(def);
+    for (const cap of capabilityRegistry.all()) {
+      const annoMatch = (cap.annotations ?? []).some((a) => scenarioTags.some((t) => t === a || t.startsWith(a + ':')));
+      const stepMatch = cap.detectsStep ? steps.some((s) => s && typeof s.text === 'string' && cap.detectsStep!(s.text)) : false;
+      if (annoMatch || stepMatch) ids.add(cap.id);
+    }
+    return [...ids];
   }
 
   /**
-   * Build the precondition bind steps for a scenario's `@query:<name>[(p={{v}},…)]` tags.
-   * Each runs the catalog query and binds the result array to a `{{name}}` variable.
+   * Precondition steps a scenario's capabilities inject (e.g. db `@query:<name>` → bind {{name}}).
+   * Each capability owns its annotation codegen via the SPI (`preconditionCodegen`); the compiler
+   * just composes + indents the returned statements (R4).
    */
-  private buildQueryBinds(scenario: ParsedScenario): Array<{ comment?: string; code: string }> {
-    const out: Array<{ comment?: string; code: string }> = [];
-    const TAG = /^@query:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
-    for (const tag of scenario.tags || []) {
-      const m = tag.match(TAG);
-      if (!m) continue;
-      const name = m[1];
-      const overrides = this.parseQueryOverrides(m[2]);
-      const entry = resolveQuery(name, this.queryScreenName); // throws (fail-fast) if missing/ambiguous
-      const { sql, paramNames } = compileQuery(entry);
-      const paramExprs = paramNames.map((p) =>
-        p in overrides ? overrides[p] : `testData.get(${JSON.stringify(p)})`,
-      );
-      const label = JSON.stringify(entry.description ? `query "${name}" — ${entry.description}` : `query "${name}"`);
-      const ds = entry.datasource ? JSON.stringify(entry.datasource) : 'undefined';
-      out.push({
-        comment: `@query:${name} → bind {{${name}}} from ${entry.datasource || 'default datasource'}`,
-        code: this.indentCode(
-          `testData.bind(${JSON.stringify(name)}, await db.fetchQuery(${label}, ${JSON.stringify(sql)}, [${paramExprs.join(', ')}], ${ds}));`,
-          4,
-        ),
-      });
-    }
-    return out;
-  }
-
-  /** Parse `@query:name(a={{x}},b="lit",c=3)` overrides → { a: "testData.get('x')", … } JS exprs. */
-  private parseQueryOverrides(raw?: string): Record<string, string> {
-    const out: Record<string, string> = {};
-    if (!raw) return out;
-    for (const part of raw.split(',')) {
-      const eq = part.indexOf('=');
-      if (eq < 0) continue;
-      const key = part.slice(0, eq).trim();
-      const val = part.slice(eq + 1).trim();
-      if (!key) continue;
-      const v = val.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
-      const q = val.match(/^["'](.*)["']$/);
-      if (v) out[key] = `testData.get(${JSON.stringify(v[1])})`;
-      else if (q) out[key] = JSON.stringify(q[1]);
-      else if (/^-?\d+(?:\.\d+)?$/.test(val)) out[key] = val;
-      else out[key] = JSON.stringify(val);
+  private capabilityPreconditions(scenario: ParsedScenario): Array<{ comment?: string; code: string; boundVars?: string[] }> {
+    discoverAndRegisterCapabilities();
+    const out: Array<{ comment?: string; code: string; boundVars?: string[] }> = [];
+    for (const cap of capabilityRegistry.all()) {
+      if (!cap.preconditionCodegen) continue;
+      out.push(...cap.preconditionCodegen({ tags: scenario.tags || [], screenName: this.queryScreenName, cwd: process.cwd() }));
     }
     return out;
   }
@@ -378,11 +362,6 @@ export class CodeGenerator {
     console.log(`✓ ${exists ? 'Updated' : 'Created'}: specs/${fileName}`);
   }
 
-  /** Ensure specs/db.ts is present and current (Data Driver runtime helper). */
-  ensureDbFile(outputDir: string): void {
-    this.syncGeneratedHelper(outputDir, 'db.ts', 'specs-db.ts');
-  }
-
   ensureBaseFile(outputDir: string): void {
     this.syncGeneratedHelper(outputDir, 'base.ts', 'specs-base.ts');
     // base.ts depends on locale-fixture.ts — keep them paired.
@@ -683,18 +662,16 @@ export class CodeGenerator {
       for (const r of refs) this.stepMapper.registerCaptured(r);
     }
 
-    // @query-bound vars: `{{name.col}}` / `{{name[2].col}}` / `{{name.count}}` exist only at
-    // runtime (the bind fetches them) — register as captured so they resolve to a runtime get()
-    // instead of a compile-time YAML lookup that would fail.
-    const queryNames = (scenario.tags || [])
-      .map((t) => t.match(/^@query:([A-Za-z_][A-Za-z0-9_]*)/))
-      .filter((m): m is RegExpMatchArray => !!m)
-      .map((m) => m[1]);
-    if (queryNames.length) {
+    // Capability preconditions (db `@query:<name>` → bind {{name}}) are owned by the capability via
+    // the SPI. Their bound `{{name.*}}` vars exist only at runtime → register them as captured so
+    // they resolve to a runtime get() instead of a compile-time YAML lookup that would fail.
+    const preconditions = this.capabilityPreconditions(scenario);
+    const boundVars = preconditions.flatMap((p) => p.boundVars || []);
+    if (boundVars.length) {
       for (const st of stepsToMap) {
         for (const mt of (st.text || '').matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) {
           const head = mt[1].split(/[.[]/)[0];
-          if (queryNames.includes(head)) this.stepMapper.registerCaptured(mt[1]);
+          if (boundVars.includes(head)) this.stepMapper.registerCaptured(mt[1]);
         }
       }
     }
@@ -728,11 +705,11 @@ export class CodeGenerator {
       }
     }
 
-    // @query:<name>[(p={{v}},…)] tags → run the catalog query as a PRECONDITION and bind its
-    // result to a `{{name}}` variable (scenario asserts on it with `expect …` + path access).
-    // Prepended so the binds run before the scenario's own steps.
-    const queryBinds = this.buildQueryBinds(scenario);
-    if (queryBinds.length) steps.unshift(...queryBinds);
+    // Capability preconditions (db `@query:<name>` → bind {{name}}; computed above) run BEFORE the
+    // scenario's own steps — prepend them, indenting the capability-supplied statements.
+    if (preconditions.length) {
+      steps.unshift(...preconditions.map((p) => ({ comment: p.comment, code: this.indentCode(p.code, 4) })));
+    }
 
     // Extract pass-through tags (feature + scenario, excluding functional tags)
     const tags = extractPassThroughTags(scenario.tags, featureTags);

package/src/generators/test-generator/patterns/index.ts

@@ -1,18 +1,8 @@
 import { ParsedStep } from '../../gherkin-parser';
 import { MappedStep } from '../step-mapper';
 import { StepPattern, PatternContext } from './types';
-import { navigationPatterns } from './navigation-patterns';
-import { formPatterns } from './form-patterns';
-import { interactionPatterns } from './interaction-patterns';
-import { assertionPatterns } from './assertion-patterns';
-import { setupPatterns } from './setup-patterns';
-import { keyboardPatterns } from './keyboard-patterns';
-import { scrollPatterns } from './scroll-patterns';
-import { scopePatterns } from './scope-patterns';
-import { tablePatterns } from './table-patterns';
-import { capturePatterns } from './capture-patterns';
-import { databasePatterns } from './database-patterns';
-import { expectPatterns } from './expect-patterns';
+import { capabilityRegistry } from '../../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
 
 /**
  * Pattern Registry - manages all step patterns
@@ -28,18 +18,11 @@ export class PatternRegistry {
    * Register default patterns from all pattern modules
    */
   private registerDefaultPatterns(): void {
-    this.patterns.push(...setupPatterns);
-    this.patterns.push(...navigationPatterns);
-    this.patterns.push(...formPatterns);
-    this.patterns.push(...interactionPatterns);
-    this.patterns.push(...assertionPatterns);
-    this.patterns.push(...keyboardPatterns);
-    this.patterns.push(...scrollPatterns);
-    this.patterns.push(...scopePatterns);
-    this.patterns.push(...tablePatterns);
-    this.patterns.push(...capturePatterns);
-    this.patterns.push(...databasePatterns);
-    this.patterns.push(...expectPatterns);
+    // Patterns are composed from the capability registry (Capability SPI, R1) instead of a
+    // hardcoded push list. Built-ins (ui · db · core) register the same set as before, so the
+    // composed list + priority sort is behaviour-identical (golden snapshots are the contract).
+    discoverAndRegisterCapabilities();
+    this.patterns.push(...capabilityRegistry.patterns());
 
     // Sort by priority (higher first)
     this.patterns.sort((a, b) => (b.priority || 0) - (a.priority || 0));
@@ -159,15 +142,6 @@ export class PatternRegistry {
   }
 }
 
-// Export pattern modules for advanced usage
-export { setupPatterns } from './setup-patterns';
-export { navigationPatterns } from './navigation-patterns';
-export { formPatterns } from './form-patterns';
-export { interactionPatterns } from './interaction-patterns';
-export { assertionPatterns } from './assertion-patterns';
-export { keyboardPatterns } from './keyboard-patterns';
-export { scrollPatterns } from './scroll-patterns';
-export { scopePatterns } from './scope-patterns';
-export { tablePatterns } from './table-patterns';
-export { databasePatterns, isDbStep } from './database-patterns';
+// The UI step patterns now live in @sungen/driver-ui (R5.4) and the DB patterns in @sungen/driver-db
+// (R5.5); both are contributed via the capability registry, not re-exported here.
 export * from './types';

package/src/generators/test-generator/template-engine.ts

@@ -229,8 +229,8 @@ export class TemplateEngine {
     this.baseContext = {};
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb });
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi });
   }
 
   renderTestFile(data: {

package/src/harness/annotation-overrides.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared annotation-override grammar for precondition annotations (`@query`/`@api`).
+ *
+ * Parses `name(a={{x}},b="lit",c=3)` overrides into a map of JS expressions, e.g.
+ * `{ a: "testData.get('x')", b: "\"lit\"", c: "3" }`. Used by the DB and API capability drivers'
+ * precondition codegen; lives in core so both drivers (and core's `api` until R5.6) can share it.
+ */
+export function parseQueryOverrides(raw?: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!raw) return out;
+  for (const part of raw.split(',')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    const key = part.slice(0, eq).trim();
+    const val = part.slice(eq + 1).trim();
+    if (!key) continue;
+    const v = val.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
+    const q = val.match(/^["'](.*)["']$/);
+    if (v) out[key] = `testData.get(${JSON.stringify(v[1])})`;
+    else if (q) out[key] = JSON.stringify(q[1]);
+    else if (/^-?\d+(?:\.\d+)?$/.test(val)) out[key] = val;
+    else out[key] = JSON.stringify(val);
+  }
+  return out;
+}

package/src/harness/audit.ts

@@ -11,7 +11,7 @@ import * as fs from 'fs';
 import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
-  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult,
+  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult, Catalog,
 } from './sensors';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
@@ -19,6 +19,9 @@ import { specCoverage, SpecCoverageResult, parseSpecClauses } from './spec-cover
 import { downstreamScope, manualOracle, readText, DownstreamResult, ManualOracleResult,
   negativeSideEffect, sourceBacked, crossArtifactOwnership } from './quality-gates';
 import { viewpointLedger, parseViewpointItems, LedgerResult } from './viewpoint-ledger';
+import { capabilityRegistry } from '../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../capabilities/discover';
+import { contextRouter } from '../capabilities/context-router';
 
 export interface AuditReport {
   screen: string;
@@ -63,13 +66,23 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
 
   const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
   const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
-  const catalog = loadCatalog();
+  // The viewpoint catalog is owned by the default (UI) capability via the SPI; falls back to the
+  // in-core loader if no capability provides one. Same catalog content → identical scores (R2).
+  discoverAndRegisterCapabilities();
+  const defaultCap = capabilityRegistry.defaultCapabilityId();
+  const catalog = ((defaultCap && capabilityRegistry.get(defaultCap)?.viewpoints?.()) as Catalog | undefined) || loadCatalog();
   const spec = specCoverage(specPath, scenarios, featureText);
 
-  const gate = viewpointGate(scenarios, viewpoints, catalog);
   // P3 — intent profile from qa/context.md drives the depth threshold (focus).
   const intent = readIntent(projectRootFromScreenDir(screenDir));
-  const depth = assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
+  // The viewpoint coverage gate + assertion depth are owned by the default (UI) capability and
+  // obtained via its `gateProvider` (R2.2b). Same functions underneath → byte-identical gate/depth
+  // → identical score. Falls back to the in-core functions if no capability provides them.
+  const uiGate = (defaultCap && capabilityRegistry.get(defaultCap)?.gateProvider) as
+    ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus }) => { gate: GateResult; depth: DepthResult }) | undefined;
+  const provided = uiGate?.({ scenarios, viewpoints, catalog, focus: intent.focus });
+  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog);
+  const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
   const claim = claimProof(scenarios, intent.focus);
   const taxonomy = taxonomyLint(scenarios);
   const balance = coverageBalance(scenarios);
@@ -125,9 +138,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (trace.mappedRatio < 0.5) {
     findings.push(`TRACE: ${trace.note}`);
   }
-  if (gate.universalGaps.length) {
-    findings.push(`UNIVERSAL: missing theme(s): ${gate.universalGaps.join(', ')} (low priority reminder).`);
-  }
+  // (UNIVERSAL viewpoint-gap finding now emitted by the `ui` gate sensor — see the gate block below.)
   for (const g of spec.triggerGaps) {
     findings.push(`TRIGGER-UNCOVERED: spec validates "${g.constraint}"${g.code ? ` (${g.code})` : ''} on [${g.required.join(', ')}] but scenarios only exercise it on [${g.found.join(', ') || 'none'}] → add a ${g.missing.join(', ')}-trigger scenario for this constraint (don't collapse the trigger × input matrix).`);
   }
@@ -157,6 +168,24 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`UNSOURCEABLE-SCENARIO: "${u}" doesn't trace to any FR / viewpoint item — link it to a source, or tag it @exploration (not part of the official suite).`);
   }
 
+  // Capability gate sensors (Capability SPI): the ContextRouter scopes WHICH gate sensors run to
+  // the capabilities this feature actually uses — generic ('core') + the default UI + any whose
+  // annotation tags appear (e.g. @query). Today core+ui gate sensors are always in scope, so this
+  // is behaviour-identical; it bounds the set as capability-specific gate sensors (@api, …) are
+  // added. Each runs over the audit context; an 'error' finding fails the gate.
+  const featureTags = [
+    ...(scenarios.some((s) => s.queryRefs && s.queryRefs.length) ? ['@query'] : []),
+    ...(scenarios.some((s) => s.apiRefs && s.apiRefs.length) ? ['@api'] : []),
+  ];
+  const routedGateIds = contextRouter.route({ target: { kind: 'screen', id: screenName }, artifact: 'feature', tags: featureTags }).gateSensorIds;
+  const gateSensorFindings = capabilityRegistry.sensors('gate')
+    .filter((s) => routedGateIds.includes(s.id))
+    .flatMap((s) => s.run({ screenName, cwd: projectRootFromScreenDir(screenDir), featureText, scenarios, universalGaps: gate.universalGaps }));
+  // Each gate sensor's message carries its own code prefix (VERIFICATION-FAIL / UNIVERSAL / …)
+  // → push verbatim.
+  for (const f of gateSensorFindings) findings.push(f.message);
+  const gateSensorError = gateSensorFindings.some((f) => f.severity === 'error');
+
   // #8 — multi-axis calibration: a high overall must not hide a weak axis.
   const manualCompleteness = manualOracleResult.manualTotal
     ? 1 - manualOracleResult.insufficient.length / manualOracleResult.manualTotal : 1;
@@ -180,7 +209,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // Gate spans coverage (viewpoint themes), depth, claim-proof, spec-clause coverage,
   // AND taxonomy-match (scenarios must use the project's viewpoint IDs when defined).
   const gateStatus: 'PASS' | 'FAIL' =
-    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' && spec.verdict !== 'fail' && !taxonomyMismatch ? 'PASS' : 'FAIL';
+    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' && spec.verdict !== 'fail' && !taxonomyMismatch && !gateSensorError ? 'PASS' : 'FAIL';
 
   return {
     screen: screenName,

package/src/harness/catalog/drivers.yaml

@@ -1,21 +1,37 @@
 # Driver Catalog (metadata only — NO driver code is bundled here).
 # Lets Sungen RECOMMEND/RESOLVE a driver that may not be installed yet, and tells
-# `sungen capability add` which package to install. See docs/spec/sungen_phase2a_spec.md.
+# `sungen capability add` which package to install. See docs/spec/sungen_phase2a_spec.md
+# and docs/spec/sungen_packaging_spec.md (R5 — the capability SPI + npm packages).
 #
-# kind: platform → the runtime/codegen adapter for a target (pick ONE per project)
-# kind: capability → an extra ability added on top of a platform (Phase 3)
-# unblocks: manual-reason codes (M1–M9) this driver can resolve (Phase 2b taxonomy)
+# Two axes:
+#   kind: platform   → HOW tests run (runtime/codegen adapter). Pick ONE per project.
+#   kind: capability → WHAT extra thing is verified, added on top of a platform.
+# Fields:
+#   status:    shipped → published as an npm package (R5);  planned → not built yet.
+#   bundled:   true → installed automatically (a dependency of @sun-asterisk/sungen),
+#              so `capability add` is unnecessary.
+#   unblocks:  manual-reason codes (M1–M9) this driver resolves (Phase 2b taxonomy).
+#
+# R5 status: the three real capabilities ship as packages — @sungen/driver-ui (web UI,
+# bundled as the default), @sungen/driver-db, @sungen/driver-api. The web *platform*
+# entry below points at @sungen/driver-ui (the UI step vocabulary + viewpoint gate); the
+# Playwright codegen *adapter* itself is still in-core (Phase 2a). Mobile + the remaining
+# capabilities are planned. See the "Platform axis & mobile evolution" section of the
+# packaging spec for the `sungen init --platform <web|mobile>` roadmap.
 
 drivers:
   web:
     kind: platform
-    package: "@sungen/driver-web"     # Phase 2a: bundled Playwright adapter serves this (back-compat)
-    runtime: playwright
-    adapter: web                       # registry adapter name
+    package: "@sungen/driver-ui"       # R5: web UI capability (step patterns + viewpoint gate)
+    status: shipped
+    bundled: true                       # @sun-asterisk/sungen depends on it → UI works out of the box
+    runtime: playwright                 # codegen adapter still in-core (Phase 2a)
+    adapter: web                        # registry adapter name
     capabilities: ["@ui"]
   mobile:
     kind: platform
     package: "@sungen/driver-mobile"
+    status: planned                     # PoC on the feat/mobile branch (Appium / Flutter)
     runtime: appium
     adapter: mobile
     capabilities: ["@ui"]
@@ -23,35 +39,42 @@ drivers:
   api:
     kind: capability
     package: "@sungen/driver-api"
+    status: shipped
     capabilities: ["@api", "@apiAssert", "@hybrid"]
     unblocks: [M2]
-  data-factory:
-    kind: capability
-    package: "@sungen/driver-data-factory"
-    capabilities: ["@dataFactory"]
-    unblocks: [M1]
   db:
     kind: capability
     package: "@sungen/driver-db"
+    status: shipped
     capabilities: ["@dbAssert"]
     unblocks: [M2]
+  data-factory:
+    kind: capability
+    package: "@sungen/driver-data-factory"
+    status: planned
+    capabilities: ["@dataFactory"]
+    unblocks: [M1]
   mock:
     kind: capability
     package: "@sungen/driver-mock"
+    status: planned
     capabilities: ["@mock", "@network"]
     unblocks: [M3]
   mail-file:
     kind: capability
     package: "@sungen/driver-mail-file"
+    status: planned
     capabilities: ["@mail", "@file"]
     unblocks: [M5]
   contract:
     kind: capability
     package: "@sungen/driver-contract"
+    status: planned
     capabilities: ["@contract"]
     unblocks: [M5]
   specialized:
     kind: capability
     package: "@sungen/driver-specialized"
+    status: planned
     capabilities: ["@specialized"]
     unblocks: [M6]

package/src/harness/parse.ts

@@ -32,6 +32,7 @@ export interface ScenarioInfo {
   vpId?: string;              // raw leading ID token of the title (project's scheme: VP0-001, MS-HP-001, VP-LIST-001)
   casesDataset?: string;      // @cases:<dataset> — data-driven; one scenario expands to N row-tests
   queryRefs?: string[];       // named queries referenced by this scenario (inline `query [name]` + @query: tags)
+  apiRefs?: string[];         // named API endpoints referenced by this scenario (@api: tags)
 }
 
 /** Format-tolerant: is this token an ID (project's scheme), not a prose word?
@@ -102,12 +103,15 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const manual = tags.includes('@manual');
   const casesTag = tags.find((t) => t.startsWith('@cases:'));
   const casesDataset = casesTag ? casesTag.slice('@cases:'.length).trim() : undefined;
-  // Named-query references: @query:<name> tags + inline `query [name]` step refs.
+  // Named-query references: @query:<name>[(overrides)] tags + inline `query [name]` step refs.
   const queryRefs = new Set<string>();
-  for (const t of tags) if (t.startsWith('@query:')) { const n = t.slice('@query:'.length).trim(); if (n) queryRefs.add(n); }
+  for (const t of tags) if (t.startsWith('@query:')) { const m = t.slice('@query:'.length).match(/^([A-Za-z_][A-Za-z0-9_]*)/); if (m) queryRefs.add(m[1]); }
   for (const step of (sc.steps as ParsedStep[]) || []) {
     for (const m of (step.text || '').matchAll(/\bquery\s+\[([A-Za-z_][A-Za-z0-9_]*)\]/gi)) queryRefs.add(m[1]);
   }
+  // Named-API references: @api:<name>[(overrides)] tags.
+  const apiRefs = new Set<string>();
+  for (const t of tags) if (t.startsWith('@api:')) { const m = t.slice('@api:'.length).match(/^([A-Za-z_][A-Za-z0-9_]*)/); if (m) apiRefs.add(m[1]); }
   let priority: Priority = 'unknown';
   for (const t of tags) if (PRIORITY_TAGS[t]) priority = PRIORITY_TAGS[t];
 
@@ -164,6 +168,7 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     vpId,
     casesDataset,
     queryRefs: queryRefs.size ? [...queryRefs] : undefined,
+    apiRefs: apiRefs.size ? [...apiRefs] : undefined,
   };
 }
 

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Public API of `@sun-asterisk/sungen` — the capability SPI plus the shared compiler/harness surface
+ * that capability drivers (`@sungen/driver-*`) build against. Drivers import from here; core never
+ * imports from a driver (discovery loads them at runtime). Keep this surface small and intentional.
+ */
+
+// --- Capability SPI ---
+export { capabilityRegistry, CapabilityRegistry } from './capabilities/registry';
+export type { CapabilityDescriptor } from './capabilities/registry';
+export type { Sensor, SensorFinding, AdvisoryScanInput, GateInput } from './capabilities/sensor';
+export type { Context, DiscoveryProvider, ContextMapper, GenerationUnit } from './capabilities/context';
+
+// --- Step-pattern authoring (a driver contributes step patterns via its descriptor) ---
+export type { PatternContext, StepPattern, StepTemplateData } from './generators/test-generator/patterns/types';
+export type { MappedStep } from './generators/test-generator/step-mapper';
+export type { ParsedStep } from './generators/gherkin-parser';
+export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';
+
+// --- Precondition-annotation override grammar (shared by the @query / @api driver codegen) ---
+export { parseQueryOverrides } from './harness/annotation-overrides';
+
+// --- Named-query catalog (shared: the DB driver's codegen + core's data-driven advisory lint) ---
+export { resolveQuery, compileQuery, lintCatalog } from './harness/query-catalog';
+export type { QueryEntry } from './harness/query-catalog';
+
+// --- Shared harness: viewpoint catalog + coverage gate / assertion depth ---
+// (the UI capability's gateProvider composes these; they also back core's ingest + audit fallback)
+export { loadCatalog, viewpointGate, assertionDepth, dataThemesFor } from './harness/sensors';
+export type { Catalog, GateResult, DepthResult } from './harness/sensors';
+export type { ScenarioInfo, ViewpointEntry } from './harness/parse';

package/src/orchestrator/templates/ai-instructions/claude-skill-gherkin-syntax.md

@@ -213,6 +213,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@flow` | Mark feature as E2E flow (cross-screen testing) |
 | `@cases:dataset` | Data-driven: run the scenario once per row of the `dataset` LIST in test-data → one `test()` per row |
 | `@query:name` | Database: run the named query from `database/queries.yaml` (precondition) and bind its rows to `{{name}}`; assert with `expect {{name.count}} …` + path access. Override params `@query:name(p={{v}})`. Repeatable. (Optional Data Driver — see Database verification above) |
+| `@api:name` | API: run the named request from `api/apis.yaml` (precondition) and bind the response to `{{name}}`; assert with `expect {{name.status}} …` + path access (`{{name.body.<path>}}`). Override params `@api:name(p={{v}})`. Repeatable. (Optional API Driver) |
 
 ### Data-driven scenarios (`@cases`)
 

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-syntax.md

@@ -213,6 +213,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@flow` | Mark feature as E2E flow (cross-screen testing) |
 | `@cases:dataset` | Data-driven: run the scenario once per row of the `dataset` LIST in test-data → one `test()` per row |
 | `@query:name` | Database: run the named query from `database/queries.yaml` (precondition) and bind its rows to `{{name}}`; assert with `expect {{name.count}} …` + path access. Override params `@query:name(p={{v}})`. Repeatable. (Optional Data Driver — see Database verification above) |
+| `@api:name` | API: run the named request from `api/apis.yaml` (precondition) and bind the response to `{{name}}`; assert with `expect {{name.status}} …` + path access (`{{name.body.<path>}}`). Override params `@api:name(p={{v}})`. Repeatable. (Optional API Driver) |
 
 ### Data-driven scenarios (`@cases`)