@sun-asterisk/sungen 3.1.1 → 3.1.2-beta.101

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/exporters/spec-parser.ts

@@ -22,7 +22,10 @@ function extractTestBlock(content: string, startIdx: number): {
   // (e.g. test('Footer "X" link', ...) — common when scenarios cite UI labels).
   // Quote char may be ' " or ` — the backtick form is a data-driven (@cases) title
   // like `VP-… — ${__row.__label}`.
-  const testRegex = /test\s*\(\s*(['"`])((?:(?!\1).)+)\1\s*,\s*(?:\{[^}]*\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
+  // The options object uses `\{.*?\}` (non-greedy, not `[^}]*`) so a tag value containing a
+  // `}` — e.g. `@query:q(p={{var}})` — doesn't truncate the match (issue #271). The header is
+  // single-line, so `.*?` anchored on `}, async` is safe.
+  const testRegex = /test\s*\(\s*(['"`])((?:(?!\1).)+)\1\s*,\s*(?:\{.*?\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
   testRegex.lastIndex = startIdx;
   const match = testRegex.exec(content);
   if (!match) return null;

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);
   }
 

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,119 +306,68 @@ 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;
   }
 
-  /** Copy the Data Driver runtime helper into specs/db.ts (idempotent). */
-  ensureDbFile(outputDir: string): void {
-    const templatesRoot = path.join(__dirname, '..', '..', 'orchestrator', 'templates');
-    const dbPath = path.join(outputDir, 'db.ts');
-    if (!fs.existsSync(dbPath)) {
-      const templatePath = path.join(templatesRoot, 'specs-db.ts');
-      if (fs.existsSync(templatePath)) {
-        if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
-        fs.copyFileSync(templatePath, dbPath);
-        console.log('✓ Created: specs/db.ts');
-      }
-    }
+  /**
+   * Copy an auto-generated runtime helper into specs/, **refreshing it when the template changed**.
+   * These files carry a `DO NOT EDIT — regenerated` header, so a stale copy left by an older sungen
+   * (e.g. a `specs/db.ts` from before a feature was added) is replaced instead of kept (issue #270).
+   * No-ops when the on-disk content already matches the template, so it stays quiet + idempotent.
+   */
+  private syncGeneratedHelper(outputDir: string, fileName: string, templateName: string): void {
+    const templatePath = path.join(__dirname, '..', '..', 'orchestrator', 'templates', templateName);
+    if (!fs.existsSync(templatePath)) return;
+    const targetPath = path.join(outputDir, fileName);
+    const next = fs.readFileSync(templatePath, 'utf8');
+    const exists = fs.existsSync(targetPath);
+    if (exists && fs.readFileSync(targetPath, 'utf8') === next) return; // already current
+    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(targetPath, next);
+    console.log(`✓ ${exists ? 'Updated' : 'Created'}: specs/${fileName}`);
   }
 
   ensureBaseFile(outputDir: string): void {
-    const templatesRoot = path.join(__dirname, '..', '..', 'orchestrator', 'templates');
-
-    const basePath = path.join(outputDir, 'base.ts');
-    if (!fs.existsSync(basePath)) {
-      const templatePath = path.join(templatesRoot, 'specs-base.ts');
-      if (fs.existsSync(templatePath)) {
-        const baseDir = path.dirname(basePath);
-        if (!fs.existsSync(baseDir)) {
-          fs.mkdirSync(baseDir, { recursive: true });
-        }
-        fs.copyFileSync(templatePath, basePath);
-        console.log('✓ Created: specs/base.ts');
-      }
-    }
-
-    // base.ts now depends on locale-fixture.ts — keep them paired.
-    const localeFixturePath = path.join(outputDir, 'locale-fixture.ts');
-    if (!fs.existsSync(localeFixturePath)) {
-      const templatePath = path.join(templatesRoot, 'specs-locale-fixture.ts');
-      if (fs.existsSync(templatePath)) {
-        const baseDir = path.dirname(localeFixturePath);
-        if (!fs.existsSync(baseDir)) {
-          fs.mkdirSync(baseDir, { recursive: true });
-        }
-        fs.copyFileSync(templatePath, localeFixturePath);
-        console.log('✓ Created: specs/locale-fixture.ts');
-      }
-    }
-
+    this.syncGeneratedHelper(outputDir, 'base.ts', 'specs-base.ts');
+    // base.ts depends on locale-fixture.ts — keep them paired.
+    this.syncGeneratedHelper(outputDir, 'locale-fixture.ts', 'specs-locale-fixture.ts');
     if (this.options.runtimeData) {
-      const testDataPath = path.join(outputDir, 'test-data.ts');
-      if (!fs.existsSync(testDataPath)) {
-        const templatePath = path.join(templatesRoot, 'specs-test-data.ts');
-        if (fs.existsSync(templatePath)) {
-          fs.copyFileSync(templatePath, testDataPath);
-          console.log('✓ Created: specs/test-data.ts');
-        }
-      }
+      this.syncGeneratedHelper(outputDir, 'test-data.ts', 'specs-test-data.ts');
     }
   }
 
@@ -707,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]);
         }
       }
     }
@@ -752,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;
+}