agentic-qe 3.14.6 → 3.14.7

package/dist/cli/handlers/init-handler.js

@@ -37,6 +37,8 @@ export class InitHandler {
             .option('--wizard', 'Run interactive setup wizard')
             .option('--auto', 'Auto-configure based on project analysis')
             .option('-u, --upgrade', 'Upgrade existing installation (overwrite skills, agents, validation)')
+            .option('--browser-engine', 'Install optional Vibium and browser payload (explicit download)', false)
+            .option('--no-browser-engine', 'Skip optional browser setup (default)')
             .option('--minimal', 'Minimal configuration (skip optional features)')
             .option('--skip-patterns', 'Skip loading pre-trained patterns')
             .option('--skip-code-index', 'Skip code intelligence pre-scan (supported escape hatch — KG can be built later via `aqe code index`, also via env AQE_SKIP_CODE_INDEX=1)')
@@ -103,7 +105,7 @@ export class InitHandler {
             if (options.wizard || options.auto) {
                 console.log(chalk.blue('\n  Agentic QE v3 Initialization\n'));
                 // Use modular orchestrator for --auto or --modular
-                if (options.auto || options.modular) {
+                if (options.auto || options.modular || options.browserEngine) {
                     await this.runModularInit(options, context);
                     return;
                 }
@@ -128,7 +130,7 @@ export class InitHandler {
             // surface it was meant to suppress.
             const noClaudeRequested = options.claude === false;
             const noStatusLineRequested = options.statusline === false;
-            if (options.modular || platformRequested || databaseFree || noClaudeRequested || noStatusLineRequested) {
+            if (options.browserEngine || options.modular || platformRequested || databaseFree || noClaudeRequested || noStatusLineRequested) {
                 console.log(chalk.blue('\n  Agentic QE v3 Initialization\n'));
                 await this.runModularInit(options, context);
                 return;
@@ -173,6 +175,7 @@ export class InitHandler {
             autoMode: options.auto,
             upgrade: options.upgrade,
             minimal: options.minimal,
+            browserEngine: options.browserEngine,
             skipPatterns: options.skipPatterns,
             skipCodeIndex: options.skipCodeIndex,
             withN8n: options.withN8n,
@@ -301,6 +304,7 @@ export class InitHandler {
             projectRoot: process.cwd(),
             autoMode: options.auto,
             minimal: options.minimal,
+            browserEngine: options.browserEngine,
             skipPatterns: options.skipPatterns,
             withN8n: options.withN8n,
         };
@@ -449,6 +453,8 @@ Options:
   -u, --upgrade              Upgrade existing installation (overwrite skills, agents, validation)
   --minimal                  Minimal configuration (skip optional features)
   --skip-patterns            Skip loading pre-trained patterns
+  --browser-engine          Install optional Vibium and browser payload
+  --no-browser-engine       Skip browser setup (default)
   --with-n8n                 Install n8n workflow testing agents and skills
   --with-opencode            Include OpenCode agent/skill provisioning
   --with-codex               Include OpenAI Codex hooks, instructions, skills, and MCP

package/dist/cli/index.js

@@ -214,6 +214,7 @@ program.hook('preAction', (_thisCommand, actionCommand) => {
 // ============================================================================
 import { registerLazyCommand, registerLazyHandler } from './lazy-registry.js';
 import { isForegroundCommandActive } from './foreground-command.js';
+import { requestOwnedShutdown } from '../kernel/process-lifecycle.js';
 registerLazyHandler(program, 'init', 'Initialize the AQE v3 system', () => import('./handlers/init-handler.js').then(m => m.createInitHandler(cleanupAndExit)), context);
 registerLazyHandler(program, 'status', 'Show system status', () => import('./handlers/status-handler.js').then(m => m.createStatusHandler(cleanupAndExit, ensureInitializedStrict)), context);
 registerLazyHandler(program, 'health', 'Check system health', () => import('./handlers/status-handler.js').then(m => m.createHealthHandler(cleanupAndExit, ensureInitializedStrict)), context);
@@ -379,12 +380,19 @@ registerLazyCommand(program, {
 // ============================================================================
 // Shutdown Handlers
 // ============================================================================
+// #801: `aqe mcp` runs the MCP server in this process and it claims the
+// lifecycle; exiting here would pre-empt its graceful shutdown (which releases
+// the shared patterns RVF lock). Every other command keeps the immediate exit.
 process.on('SIGINT', async () => {
+    if (requestOwnedShutdown('SIGINT'))
+        return;
     console.log(chalk.yellow('\n\nShutting down...'));
     console.log(chalk.green('Shutdown complete\n'));
     await cleanupAndExit(0);
 });
 process.on('SIGTERM', async () => {
+    if (requestOwnedShutdown('SIGTERM'))
+        return;
     console.log(chalk.yellow('\nReceived SIGTERM, shutting down gracefully...'));
     await cleanupAndExit(0);
 });

package/dist/coordination/handlers/test-execution-handlers.js

@@ -87,7 +87,7 @@ export function registerTestExecutionHandlers(ctx) {
                 // Return a graceful fallback with warning when no source files provided
                 return ok({
                     testsGenerated: 0,
-                    coverageEstimate: 0,
+                    coverageEstimate: null,
                     tests: [],
                     patternsUsed: [],
                     warning: 'No source files or code provided for test generation. Provide sourceCode, filePath, or sourceFiles in the payload.',
@@ -111,6 +111,7 @@ export function registerTestExecutionHandlers(ctx) {
                 coverageTarget: payload.coverageGoal || 80,
                 patterns: [],
                 importPathOverrides,
+                behaviorExamples: payload.behaviorExamples,
             });
             // Always clean up the temp file we created — even on failure
             if (tempPath) {
@@ -134,6 +135,8 @@ export function registerTestExecutionHandlers(ctx) {
                     type: t.type,
                     sourceFile: rewritten.sourceFile,
                     assertions: t.assertions,
+                    generationMode: t.generationMode,
+                    generationLimits: t.generationLimits,
                     testCode: rewritten.testCode,
                 };
             });
@@ -148,13 +151,15 @@ export function registerTestExecutionHandlers(ctx) {
                 patternsUsed: generatedTests.patternsUsed,
                 llmEnhanced,
                 ...(llmEnhanced ? {} : {
-                    generationMode: 'deterministic-template',
-                    note: payload.aiEnhancement === false
-                        ? 'LLM enhancement was disabled by the caller (aiEnhancement: false).'
-                        : 'No LLM provider was available, so tests are deterministic template ' +
-                            'scaffolding rather than source-aware. Configure a provider in ' +
-                            '.agentic-qe/llm-config.json (or set a provider API key) and ensure ' +
-                            'AQE_LLM_ROUTER_DISABLED is not set.',
+                    generationMode: generatedTests.tests.some(t => t.generationMode === 'behavior-examples') ? 'behavior-examples' : 'deterministic-template',
+                    note: generatedTests.tests.some(t => t.generationMode === 'behavior-examples')
+                        ? 'Assertions use caller-supplied specification examples. Coverage is unmeasured; inspect generationLimits on each test.'
+                        : payload.aiEnhancement === false
+                            ? 'LLM enhancement was disabled by the caller (aiEnhancement: false). Coverage is unmeasured; inspect generationLimits on each test.'
+                            : 'No LLM provider was available, so tests are deterministic template ' +
+                                'scaffolding rather than source-aware. Configure a provider in ' +
+                                '.agentic-qe/llm-config.json (or set a provider API key) and ensure ' +
+                                'AQE_LLM_ROUTER_DISABLED is not set.',
                 }),
             });
         }

package/dist/coordination/index.d.ts

@@ -7,7 +7,7 @@ export * from './consensus';
 export * from './claims';
 export type { Protocol, ProtocolSchedule, ProtocolAction, ProtocolExecution, ProtocolExecutionStatus, ActionExecutionResult, ActionExecutionStatus, ProtocolExecutor, WorkflowDefinition as CrossDomainWorkflowDefinition, WorkflowStep as CrossDomainWorkflowStep, WorkflowCondition, WorkflowTrigger as CrossDomainWorkflowTrigger, WorkflowHandler, WorkflowContext as CrossDomainWorkflowContext, WorkflowExecution as CrossDomainWorkflowExecution, WorkflowExecutionStatus as CrossDomainWorkflowExecutionStatus, StepExecutionResult as CrossDomainStepExecutionResult, WorkflowExecutor, CrossDomainHandler, CrossDomainHandlerConfig, DomainRoute, EventSubscription, EventCorrelation, EventAggregation, CrossDomainRouter, } from './interfaces';
 export { TaskAuditLogger, createTaskAuditLogger, } from './services';
-export type { TaskAuditEntry, TaskAuditConfig, TaskOperation, } from './services';
+export type { TaskAuditEntry, TaskAuditSequencedEntry, TaskAuditConfig, TaskAuditFilter, TaskAuditWindow, TaskAuditSnapshot, TaskOperation, } from './services';
 export { CrossDomainEventRouter, createCrossDomainRouter, } from './cross-domain-router';
 export { DefaultProtocolExecutor, createProtocolExecutor, } from './protocol-executor';
 export { WorkflowOrchestrator, createWorkflowOrchestrator, WorkflowEvents, } from './workflow-orchestrator';

package/dist/coordination/queen-event-handlers.js

@@ -162,7 +162,7 @@ export async function handleTaskCompleted(ctx, event) {
 // Task failed handler
 // ============================================================================
 export async function handleTaskFailed(ctx, event) {
-    const { taskId, error } = event.payload;
+    const { taskId, error, callerError } = event.payload;
     const cancelled = settleCancelledTask(ctx.tasks, taskId);
     if (cancelled.ignored) {
         if (cancelled.settledNow) {
@@ -177,8 +177,10 @@ export async function handleTaskFailed(ctx, event) {
         if (execution.status === 'running' || execution.status === 'assigned') {
             ctx.runningTaskCounter = Math.max(0, ctx.runningTaskCounter - 1);
         }
-        // ADR-064: Record failure in domain circuit breaker
-        if (ctx.domainBreakerRegistry && execution.assignedDomain) {
+        // ADR-064: Record failure in domain circuit breaker. A task rejected for
+        // invalid caller input says nothing about the domain's health, so it must
+        // not open the breaker for every other caller (#795).
+        if (ctx.domainBreakerRegistry && execution.assignedDomain && !callerError) {
             ctx.domainBreakerRegistry.getBreaker(execution.assignedDomain).recordFailure(new Error(error || 'Task failed'));
         }
         // ADR-064 Phase 3: Fail the trace span for this task
@@ -189,8 +191,9 @@ export async function handleTaskFailed(ctx, event) {
                 ctx.taskTraceContexts.delete(taskId);
             }
         }
-        // Check if we should retry
-        if (execution.retryCount < ctx.config.taskRetryLimit) {
+        // Check if we should retry. Caller-input errors are deterministic, so a
+        // retry would fail the same way.
+        if (!callerError && execution.retryCount < ctx.config.taskRetryLimit) {
             ctx.auditLogger.logFail(taskId, execution.assignedAgents[0], error);
             const retried = {
                 ...execution,
@@ -227,7 +230,7 @@ export async function handleTaskFailed(ctx, event) {
             }
             // ADR-064 Phase 4A: Create competing hypotheses investigation for
             // permanent failures in critical domains (p0/p1 priority)
-            if (ctx.hypothesisManager && (execution.task.priority === 'p0' || execution.task.priority === 'p1')) {
+            if (!callerError && ctx.hypothesisManager && (execution.task.priority === 'p0' || execution.task.priority === 'p1')) {
                 try {
                     const domain = execution.assignedDomain || 'test-generation';
                     const investigation = ctx.hypothesisManager.createInvestigation(taskId, domain, `Root cause analysis for ${execution.task.type} failure: ${error}`);

package/dist/coordination/result-saver.js

@@ -372,7 +372,7 @@ end_of_record
 | Metric | Value |
 |--------|-------|
 | Tests Generated | ${data.testsGenerated} |
-| Coverage Estimate | ${data.coverageEstimate}% |
+| Coverage Estimate | ${data.coverageEstimate == null ? 'Unmeasured' : data.coverageEstimate + '%'} |
 | Patterns Used | ${data.patternsUsed.length} |
 
 ## Patterns Applied

package/dist/coordination/services/index.d.ts

@@ -2,5 +2,5 @@
  * Agentic QE v3 - Coordination Services
  * Exports services used by coordination components
  */
-export { TaskAuditLogger, createTaskAuditLogger, type TaskAuditEntry, type TaskAuditConfig, type TaskOperation, } from './task-audit-logger';
+export { TaskAuditLogger, createTaskAuditLogger, type TaskAuditEntry, type TaskAuditSequencedEntry, type TaskAuditConfig, type TaskAuditFilter, type TaskAuditWindow, type TaskAuditSnapshot, type TaskOperation, } from './task-audit-logger';
 //# sourceMappingURL=index.d.ts.map

package/dist/coordination/services/task-audit-logger.d.ts

@@ -21,6 +21,34 @@ export interface TaskAuditEntry {
     readonly domain?: DomainName;
     readonly details?: Record<string, unknown>;
 }
+/** An entry produced by this logger, positioned within its generation. */
+export interface TaskAuditSequencedEntry extends TaskAuditEntry {
+    readonly sequence: number;
+}
+/** Filters select retained entries; they do not change retention metadata. */
+export interface TaskAuditFilter {
+    operation?: TaskOperation;
+    taskId?: string;
+    agentId?: string;
+    domain?: DomainName;
+    fromTimestamp?: Date;
+    toTimestamp?: Date;
+    limit?: number;
+}
+/** Completeness of the bounded observation window since construction/clear. */
+export interface TaskAuditWindow {
+    generation: string;
+    recordedEntries: number;
+    retainedEntries: number;
+    droppedEntries: number;
+    firstRetainedSequence: number | null;
+    lastRetainedSequence: number | null;
+    disposition: 'complete' | 'truncated';
+}
+/** Filtered entries with metadata for the entire retained window. */
+export interface TaskAuditSnapshot extends TaskAuditWindow {
+    entries: TaskAuditSequencedEntry[];
+}
 /**
  * Configuration for task audit logger
  */
@@ -41,6 +69,9 @@ export interface TaskAuditConfig {
 export declare class TaskAuditLogger {
     private readonly entries;
     private readonly config;
+    private generation;
+    private recordedEntries;
+    private droppedEntries;
     constructor(config?: Partial<TaskAuditConfig>);
     /**
      * Log a task operation
@@ -65,19 +96,13 @@ export declare class TaskAuditLogger {
     /**
      * Get audit entries with optional filtering
      */
-    getEntries(filter?: {
-        operation?: TaskOperation;
-        taskId?: string;
-        agentId?: string;
-        domain?: DomainName;
-        fromTimestamp?: Date;
-        toTimestamp?: Date;
-        limit?: number;
-    }): TaskAuditEntry[];
-    /**
-     * Get statistics about task operations
-     */
-    getStatistics(): {
+    getEntries(filter?: TaskAuditFilter): TaskAuditSequencedEntry[];
+    /** Get selected entries without losing evidence of earlier evictions/resets. */
+    getSnapshot(filter?: TaskAuditFilter): TaskAuditSnapshot;
+    private getWindow;
+    /** Get counts for the retained window, with its completeness metadata. */
+    getStatistics(): TaskAuditWindow & {
+        basis: 'retained-window';
         totalEntries: number;
         operationCounts: Record<TaskOperation, number>;
         taskCount: number;

package/dist/coordination/services/task-audit-logger.js

@@ -5,6 +5,7 @@
  * This replaces the full authorization service with simple audit logging
  * for a local CLI tool where all agents are trusted.
  */
+import { randomUUID } from 'node:crypto';
 const DEFAULT_CONFIG = {
     enableConsoleLog: true,
     maxEntries: 1000,
@@ -19,14 +20,21 @@ const DEFAULT_CONFIG = {
 export class TaskAuditLogger {
     entries = [];
     config;
+    generation = randomUUID();
+    recordedEntries = 0;
+    droppedEntries = 0;
     constructor(config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
+        if (!Number.isSafeInteger(this.config.maxEntries) || this.config.maxEntries < 0) {
+            throw new RangeError('maxEntries must be a non-negative safe integer');
+        }
     }
     /**
      * Log a task operation
      */
     log(operation, taskId, options) {
         const entry = {
+            sequence: ++this.recordedEntries,
             timestamp: new Date(),
             operation,
             taskId,
@@ -37,7 +45,9 @@ export class TaskAuditLogger {
         this.entries.push(entry);
         // Trim if exceeds max
         if (this.entries.length > this.config.maxEntries) {
-            this.entries.splice(0, this.entries.length - this.config.maxEntries);
+            const dropped = this.entries.length - this.config.maxEntries;
+            this.entries.splice(0, dropped);
+            this.droppedEntries += dropped;
         }
         // Console log if enabled
         if (this.config.enableConsoleLog) {
@@ -102,11 +112,24 @@ export class TaskAuditLogger {
             }
         }
         const limit = filter?.limit ?? result.length;
-        return result.slice(-limit);
+        return limit === 0 ? [] : result.slice(-limit);
     }
-    /**
-     * Get statistics about task operations
-     */
+    /** Get selected entries without losing evidence of earlier evictions/resets. */
+    getSnapshot(filter) {
+        return { ...this.getWindow(), entries: this.getEntries(filter) };
+    }
+    getWindow() {
+        return {
+            generation: this.generation,
+            recordedEntries: this.recordedEntries,
+            retainedEntries: this.entries.length,
+            droppedEntries: this.droppedEntries,
+            firstRetainedSequence: this.entries[0]?.sequence ?? null,
+            lastRetainedSequence: this.entries[this.entries.length - 1]?.sequence ?? null,
+            disposition: this.droppedEntries > 0 ? 'truncated' : 'complete',
+        };
+    }
+    /** Get counts for the retained window, with its completeness metadata. */
     getStatistics() {
         const operationCounts = {
             submit: 0,
@@ -129,6 +152,8 @@ export class TaskAuditLogger {
             }
         }
         return {
+            ...this.getWindow(),
+            basis: 'retained-window',
             totalEntries: this.entries.length,
             operationCounts,
             taskCount: taskIds.size,
@@ -140,6 +165,9 @@ export class TaskAuditLogger {
      */
     clear() {
         this.entries.length = 0;
+        this.generation = randomUUID();
+        this.recordedEntries = 0;
+        this.droppedEntries = 0;
     }
 }
 /**

package/dist/coordination/task-executor.d.ts

@@ -154,6 +154,11 @@ export declare class DomainTaskExecutor implements TaskHandlerContext {
     private getTaskDomain;
     private timeout;
     private publishTaskCompleted;
+    /**
+     * @param callerError true when the task was rejected because of invalid
+     *   caller input; the queen then neither retries it nor counts it toward
+     *   the domain circuit breaker.
+     */
     private publishTaskFailed;
 }
 export declare function createTaskExecutor(kernel: QEKernel, config?: Partial<TaskExecutorConfig>): DomainTaskExecutor;

package/dist/coordination/task-executor.js

@@ -13,7 +13,7 @@
  * Handler implementations are extracted into ./handlers/ modules.
  */
 import { v4 as uuidv4 } from 'uuid';
-import { toErrorMessage } from '../shared/error-utils.js';
+import { isCallerInputError, toErrorMessage } from '../shared/error-utils.js';
 import { createResultSaver } from './result-saver.js';
 import { createLogger } from '../logging/logger-factory.js';
 import { getClaudeModelForTier } from '../shared/llm/model-registry.js';
@@ -436,7 +436,7 @@ export class DomainTaskExecutor {
             ]);
             if (!result.success) {
                 const errorMsg = 'error' in result ? result.error.message : 'Unknown error';
-                await this.publishTaskFailed(task.id, errorMsg, domain);
+                await this.publishTaskFailed(task.id, errorMsg, domain, 'error' in result && isCallerInputError(result.error));
                 // ADR-051: Record failed outcome
                 this.recordOutcome(task, routingTier, false, Date.now() - startTime).catch((e) => { logger.warn('recordOutcome failed', { error: e instanceof Error ? e.message : String(e), taskId: task.id }); });
                 return {
@@ -486,7 +486,7 @@ export class DomainTaskExecutor {
         }
         catch (error) {
             const errorMessage = toErrorMessage(error);
-            await this.publishTaskFailed(task.id, errorMessage, domain);
+            await this.publishTaskFailed(task.id, errorMessage, domain, isCallerInputError(error));
             // ADR-051: Record failed outcome
             this.recordOutcome(task, routingTier, false, Date.now() - startTime).catch((e) => { logger.warn('recordOutcome failed', { error: e instanceof Error ? e.message : String(e), taskId: task.id }); });
             return {
@@ -655,13 +655,18 @@ export class DomainTaskExecutor {
             payload: { taskId, result },
         });
     }
-    async publishTaskFailed(taskId, error, domain) {
+    /**
+     * @param callerError true when the task was rejected because of invalid
+     *   caller input; the queen then neither retries it nor counts it toward
+     *   the domain circuit breaker.
+     */
+    async publishTaskFailed(taskId, error, domain, callerError = false) {
         await this.eventBus.publish({
             id: uuidv4(),
             type: 'TaskFailed',
             timestamp: new Date(),
             source: domain,
-            payload: { taskId, error },
+            payload: { taskId, error, ...(callerError ? { callerError: true } : {}) },
         });
     }
 }

package/dist/domains/test-generation/coordinator.js

@@ -249,7 +249,7 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
             this.startWorkflow(workflowId, 'generate');
             // Opt-in (plan 06, D7-wire): try the FREE local model first with a repair
             // loop. Fully guarded — any miss falls through to the normal LLM path.
-            if (this.freeTierExecutor) {
+            if (this.freeTierExecutor && !request.behaviorExamples?.length) {
                 try {
                     const ft = await this.tryFreeTierGeneration(request);
                     if (ft) {
@@ -354,11 +354,12 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
                     }
                 }
                 // Three-loop protocol: instantAdapt must precede recordOutcome
-                if (isSONAThreeLoopEnabled() && this.qesona?.isThreeLoopEnabled()) {
+                const coverageEstimate = result.value.coverageEstimate;
+                if (coverageEstimate !== null && isSONAThreeLoopEnabled() && this.qesona?.isThreeLoopEnabled()) {
                     const tests = result.value;
                     this.qesona.instantAdapt([
                         tests.tests.length / 20,
-                        tests.coverageEstimate / 100,
+                        coverageEstimate / 100,
                         tests.patternsUsed.length / 10,
                         request.sourceFiles.length / 20,
                         (request.coverageTarget ?? 80) / 100,
@@ -476,7 +477,7 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
             framework,
             llmEnhanced: true,
         };
-        return { tests: [test], coverageEstimate: 0, patternsUsed: ['free-tier-local', `tier:${r.tierUsed}`] };
+        return { tests: [test], coverageEstimate: null, patternsUsed: ['free-tier-local', `tier:${r.tierUsed}`] };
     }
     /**
      * Generate tests using TDD workflow
@@ -953,7 +954,7 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
      * Per ADR-040: Store test generation patterns in SONA
      */
     async storeTestGenerationPattern(tests, request) {
-        if (!this.qesona) {
+        if (!this.qesona || tests.coverageEstimate === null) {
             return;
         }
         try {

package/dist/domains/test-generation/interfaces.d.ts

@@ -16,7 +16,14 @@ export interface ITestGenerationAPI {
     /** Learn patterns from existing tests */
     learnPatterns(request: ILearnPatternsRequest): Promise<Result<ILearnedPatterns, Error>>;
 }
+/** Caller-owned specifications; expected values are never inferred from source. */
+export interface BehaviorExample {
+    functionName: string;
+    args: unknown[];
+    expected: unknown;
+}
 export interface IGenerateTestsRequest {
+    behaviorExamples?: BehaviorExample[];
     sourceFiles: string[];
     testType: 'unit' | 'integration' | 'e2e';
     framework?: TestFramework;
@@ -41,7 +48,8 @@ export interface IGenerateTestsRequest {
 }
 export interface IGeneratedTests {
     tests: IGeneratedTest[];
-    coverageEstimate: number;
+    /** null means unmeasured; never coerce unknown coverage to measured zero. */
+    coverageEstimate: number | null;
     /** Human-readable pattern names, for display (reports, CLI output). */
     patternsUsed: string[];
     /** Real qe_patterns.id values for the same patterns, for usage/ADR-110 tracking. */
@@ -61,6 +69,8 @@ export interface IGeneratedTest {
     compilationErrors?: string[];
     /** ADR-051: Whether test was enhanced by LLM */
     llmEnhanced?: boolean;
+    generationMode?: 'behavior-examples' | 'scaffolding';
+    generationLimits?: string[];
     /** Test quality gate validation result (loki-mode Gates 8 & 9) */
     qualityGateResult?: TestQualityGateResult;
     /** ADR-062: Whether this test is a holdout test (not shown to developer, runs in CI only) */

package/dist/domains/test-generation/services/behavior-example-validation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Boundary validation for caller-supplied behavior examples (#787 / #795).
+ *
+ * Shared by the MCP handlers, the CLI `--behavior-examples` path and the
+ * domain service so every entry point rejects the same malformed input with
+ * the same message. Failures are `CallerInputError`s: they are the caller's
+ * problem, not a sign of an unhealthy test-generation domain, and must never
+ * count toward its circuit breaker.
+ *
+ * Only the shape is checked here. Whether `functionName` exists in the source
+ * and whether `args` matches its arity can only be decided against the parsed
+ * source (see behavior-examples.ts), which also throws `CallerInputError`.
+ *
+ * Kept free of heavy imports (no `typescript`) so boundary layers can use it.
+ */
+import type { BehaviorExample } from '../interfaces.js';
+/**
+ * JSON Schema for one `behaviorExamples` element. Single source of truth for
+ * every tool definition that advertises `behaviorExamples` (protocol server
+ * `test_generate_enhanced` and `qe/tests/generate`).
+ */
+export declare const BEHAVIOR_EXAMPLE_ITEM_SCHEMA: Record<string, unknown>;
+/**
+ * Throw unless `value` is plain JSON data that can be emitted as a literal:
+ * finite numbers (no -0), strings, booleans, null, arrays and plain objects,
+ * without cycles.
+ */
+export declare function assertBehaviorJsonValue(value: unknown, label?: string): void;
+/**
+ * Validate the shape of `behaviorExamples` at a system boundary.
+ *
+ * @returns the examples typed as `BehaviorExample[]`, or `undefined` when omitted
+ * @throws CallerInputError describing the first invalid entry
+ */
+export declare function validateBehaviorExamples(value: unknown): BehaviorExample[] | undefined;
+//# sourceMappingURL=behavior-example-validation.d.ts.map

package/dist/domains/test-generation/services/behavior-example-validation.js

@@ -0,0 +1,89 @@
+/**
+ * Boundary validation for caller-supplied behavior examples (#787 / #795).
+ *
+ * Shared by the MCP handlers, the CLI `--behavior-examples` path and the
+ * domain service so every entry point rejects the same malformed input with
+ * the same message. Failures are `CallerInputError`s: they are the caller's
+ * problem, not a sign of an unhealthy test-generation domain, and must never
+ * count toward its circuit breaker.
+ *
+ * Only the shape is checked here. Whether `functionName` exists in the source
+ * and whether `args` matches its arity can only be decided against the parsed
+ * source (see behavior-examples.ts), which also throws `CallerInputError`.
+ *
+ * Kept free of heavy imports (no `typescript`) so boundary layers can use it.
+ */
+import { CallerInputError } from '../../../shared/error-utils.js';
+const SHAPE_HINT = 'expected [{ "functionName": "add", "args": [2, 3], "expected": 5 }]';
+/**
+ * JSON Schema for one `behaviorExamples` element. Single source of truth for
+ * every tool definition that advertises `behaviorExamples` (protocol server
+ * `test_generate_enhanced` and `qe/tests/generate`).
+ */
+export const BEHAVIOR_EXAMPLE_ITEM_SCHEMA = {
+    type: 'object',
+    description: 'One caller-owned specification example',
+    properties: {
+        functionName: { type: 'string', description: 'Named export of the source file to call' },
+        args: { type: 'array', description: 'Positional JSON arguments; length must equal the function arity', items: {} },
+        expected: { description: 'Expected JSON return value (use null for a null result)' },
+    },
+    required: ['functionName', 'args', 'expected'],
+};
+/**
+ * Throw unless `value` is plain JSON data that can be emitted as a literal:
+ * finite numbers (no -0), strings, booleans, null, arrays and plain objects,
+ * without cycles.
+ */
+export function assertBehaviorJsonValue(value, label = 'Behavior example value') {
+    const visit = (v, seen) => {
+        if (v === null || typeof v === 'string' || typeof v === 'boolean')
+            return;
+        if (typeof v === 'number' && Number.isFinite(v) && !Object.is(v, -0))
+            return;
+        if (typeof v !== 'object' || seen.has(v)) {
+            throw new CallerInputError(`${label} must be finite JSON data (no undefined, functions, NaN/Infinity, cycles, or negative zero)`);
+        }
+        if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null) {
+            throw new CallerInputError(`${label} must contain only plain JSON objects`);
+        }
+        seen.add(v);
+        for (const item of Array.isArray(v) ? Array.from(v) : Object.values(v))
+            visit(item, seen);
+        seen.delete(v);
+    };
+    visit(value, new Set());
+}
+/**
+ * Validate the shape of `behaviorExamples` at a system boundary.
+ *
+ * @returns the examples typed as `BehaviorExample[]`, or `undefined` when omitted
+ * @throws CallerInputError describing the first invalid entry
+ */
+export function validateBehaviorExamples(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new CallerInputError(`behaviorExamples must be an array; ${SHAPE_HINT}`);
+    }
+    value.forEach((example, index) => {
+        const at = `behaviorExamples[${index}]`;
+        if (typeof example !== 'object' || example === null || Array.isArray(example)) {
+            throw new CallerInputError(`${at} must be an object; ${SHAPE_HINT}`);
+        }
+        const record = example;
+        if (typeof record.functionName !== 'string' || record.functionName.trim() === '') {
+            throw new CallerInputError(`${at}.functionName must be a non-empty string`);
+        }
+        if (!Array.isArray(record.args)) {
+            throw new CallerInputError(`${at}.args must be an array of arguments`);
+        }
+        if (!Object.prototype.hasOwnProperty.call(record, 'expected')) {
+            throw new CallerInputError(`${at}.expected is required (use null for a null result)`);
+        }
+        assertBehaviorJsonValue(record.args, `${at}.args`);
+        assertBehaviorJsonValue(record.expected, `${at}.expected`);
+    });
+    return value;
+}
+//# sourceMappingURL=behavior-example-validation.js.map

package/dist/domains/test-generation/services/behavior-examples.d.ts

@@ -0,0 +1,8 @@
+import type { BehaviorExample } from '../interfaces.js';
+export declare function generateBehaviorExamples(source: string, sourceFile: string, importPath: string, framework: string, examples: BehaviorExample[] | undefined, testType: string): {
+    code: string;
+    limits: string[];
+    assertions: number;
+    mode: "behavior-examples" | "scaffolding";
+};
+//# sourceMappingURL=behavior-examples.d.ts.map