@scenarist/core 0.2.0 → 0.3.0

package/dist/domain/response-selector.js

@@ -1,9 +1,11 @@
-import { ResponseSelectionError } from "../ports/driven/response-selector.js";
+import { ScenaristError, ErrorCodes } from "../types/errors.js";
 import { extractFromPath } from "./path-extraction.js";
 import { applyTemplates } from "./template-replacement.js";
 import { matchesRegex } from "./regex-matching.js";
 import { createStateResponseResolver } from "./state-response-resolver.js";
 import { deepEquals } from "./deep-equals.js";
+import { noOpLogger } from "../adapters/index.js";
+import { LogCategories, LogEvents } from "./log-events.js";
 const SPECIFICITY_RANGES = {
     MATCH_CRITERIA_BASE: 100,
     SEQUENCE_FALLBACK: 1,
@@ -21,26 +23,41 @@ const SPECIFICITY_RANGES = {
  * @param options.stateManager - Optional state manager for capture/injection (Phase 3)
  */
 export const createResponseSelector = (options = {}) => {
-    const { sequenceTracker, stateManager } = options;
+    const { sequenceTracker, stateManager, logger = noOpLogger } = options;
     return {
         selectResponse(testId, scenarioId, context, mocks) {
+            const logContext = { testId, scenarioId };
+            // Log the number of candidate mocks
+            logger.debug(LogCategories.MATCHING, LogEvents.MOCK_CANDIDATES_FOUND, logContext, {
+                count: mocks.length,
+            });
             let bestMatch = null;
+            // Track if we skipped any exhausted sequences (for better error messages)
+            let skippedExhaustedSequences = false;
             // Find all matching mocks and score them by specificity
             for (let mockIndex = 0; mockIndex < mocks.length; mockIndex++) {
-                // Index is guaranteed in bounds by loop condition (0 <= mockIndex < length)
+                // eslint-disable-next-line security/detect-object-injection -- Index bounded by loop (0 <= i < length)
                 const mockWithParams = mocks[mockIndex];
                 const mock = mockWithParams.mock;
                 // Skip exhausted sequences (repeat: 'none' that have been exhausted)
                 if (mock.sequence && sequenceTracker) {
                     const { exhausted } = sequenceTracker.getPosition(testId, scenarioId, mockIndex);
                     if (exhausted) {
+                        skippedExhaustedSequences = true;
                         continue; // Skip to next mock, allowing fallback to be selected
                     }
                 }
                 // Check if this mock has match criteria
                 if (mock.match) {
                     // If match criteria exists, check if it matches the request
-                    if (matchesCriteria(context, mock.match, testId, stateManager)) {
+                    const matched = matchesCriteria(context, mock.match, testId, stateManager);
+                    // Log the evaluation result
+                    logger.debug(LogCategories.MATCHING, LogEvents.MOCK_MATCH_EVALUATED, logContext, {
+                        mockIndex,
+                        matched,
+                        hasCriteria: true,
+                    });
+                    if (matched) {
                         // Match criteria always have higher priority than fallbacks
                         // Base specificity ensures even 1 field beats any fallback
                         const specificity = SPECIFICITY_RANGES.MATCH_CRITERIA_BASE +
@@ -55,9 +72,16 @@ export const createResponseSelector = (options = {}) => {
                     continue;
                 }
                 // No match criteria = fallback mock (always matches)
-                // Sequences get higher priority than simple responses
-                // This ensures sequences are selected over simple fallback responses
-                const fallbackSpecificity = mock.sequence
+                // Log fallback evaluation
+                logger.debug(LogCategories.MATCHING, LogEvents.MOCK_MATCH_EVALUATED, logContext, {
+                    mockIndex,
+                    matched: true,
+                    hasCriteria: false,
+                });
+                // Dynamic response types (sequence, stateResponse) get higher priority than simple responses
+                // This ensures they are selected over simple fallback responses
+                // Both sequence and stateResponse get the same specificity (Issue #316 fix)
+                const fallbackSpecificity = mock.sequence || mock.stateResponse
                     ? SPECIFICITY_RANGES.SEQUENCE_FALLBACK
                     : SPECIFICITY_RANGES.SIMPLE_FALLBACK;
                 if (!bestMatch || fallbackSpecificity >= bestMatch.specificity) {
@@ -73,14 +97,29 @@ export const createResponseSelector = (options = {}) => {
             }
             // Return the best matching mock
             if (bestMatch) {
-                const { mockWithParams, mockIndex } = bestMatch;
+                const { mockWithParams, mockIndex, specificity } = bestMatch;
                 const mock = mockWithParams.mock;
+                // Log successful selection
+                logger.info(LogCategories.MATCHING, LogEvents.MOCK_SELECTED, logContext, {
+                    mockIndex,
+                    specificity,
+                });
                 // Select response (single, sequence, or stateResponse)
                 const response = selectResponseFromMock(testId, scenarioId, mockIndex, mock, sequenceTracker, stateManager);
                 if (!response) {
                     return {
                         success: false,
-                        error: new ResponseSelectionError(`Mock has neither response nor sequence field`),
+                        error: new ScenaristError(`Mock has neither response nor sequence field`, {
+                            code: ErrorCodes.VALIDATION_ERROR,
+                            context: {
+                                testId,
+                                scenarioId,
+                                mockInfo: {
+                                    index: mockIndex,
+                                },
+                                hint: "Each mock must have a 'response', 'sequence', or 'stateResponse' field.",
+                            },
+                        }),
                     };
                 }
                 // Phase 3: Capture state from request if configured
@@ -105,10 +144,48 @@ export const createResponseSelector = (options = {}) => {
                 }
                 return { success: true, data: finalResponse };
             }
-            // No mock matched
+            // No mock matched - determine specific error type
+            if (skippedExhaustedSequences) {
+                // All matching mocks were exhausted sequences
+                logger.warn(LogCategories.SEQUENCE, LogEvents.SEQUENCE_EXHAUSTED, logContext, {
+                    url: context.url,
+                    method: context.method,
+                });
+                return {
+                    success: false,
+                    error: new ScenaristError(`Sequence exhausted for ${context.method} ${context.url}. All responses have been consumed and repeat mode is 'none'.`, {
+                        code: ErrorCodes.SEQUENCE_EXHAUSTED,
+                        context: {
+                            testId,
+                            scenarioId,
+                            requestInfo: {
+                                method: context.method,
+                                url: context.url,
+                            },
+                            hint: "Add a fallback mock to handle requests after sequence exhaustion, or use repeat: 'last' or 'cycle' instead of 'none'.",
+                        },
+                    }),
+                };
+            }
+            logger.warn(LogCategories.MATCHING, LogEvents.MOCK_NO_MATCH, logContext, {
+                url: context.url,
+                method: context.method,
+                candidateCount: 0,
+            });
             return {
                 success: false,
-                error: new ResponseSelectionError(`No mock matched for ${context.method} ${context.url}`),
+                error: new ScenaristError(`No mock matched for ${context.method} ${context.url}`, {
+                    code: ErrorCodes.NO_MOCK_FOUND,
+                    context: {
+                        testId,
+                        scenarioId,
+                        requestInfo: {
+                            method: context.method,
+                            url: context.url,
+                        },
+                        hint: "Add a fallback mock (without match criteria) to handle unmatched requests, or add a mock with matching criteria.",
+                    },
+                }),
             };
         },
     };
@@ -136,6 +213,7 @@ const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTra
         // Get response at current position
         // Note: Exhausted sequences are skipped during matching phase,
         // so position should always be valid here
+        // eslint-disable-next-line security/detect-object-injection -- Position bounded by sequence tracker
         const response = mock.sequence.responses[position];
         // Advance position for next call
         const repeatMode = mock.sequence.repeat || "last";
@@ -275,6 +353,7 @@ const matchesState = (stateCriteria, testId, stateManager) => {
             return false;
         }
         // Deep equality check for values (handles primitives, null, objects)
+        // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
         if (!deepEquals(currentState[key], expectedValue)) {
             return false;
         }
@@ -295,6 +374,7 @@ const matchesBody = (requestBody, criteriaBody) => {
     const body = requestBody;
     // Check all required fields exist in request body with matching values
     for (const [key, criteriaValue] of Object.entries(criteriaBody)) {
+        // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
         const requestValue = body[key];
         // Convert to string for matching (type coercion like headers/query)
         const stringValue = requestValue == null ? "" : String(requestValue);
@@ -377,6 +457,7 @@ const matchesHeaders = (requestHeaders, criteriaHeaders) => {
     const normalizedRequest = createNormalizedHeaderMap(requestHeaders);
     for (const [key, value] of Object.entries(criteriaHeaders)) {
         const normalizedKey = normalizeHeaderName(key);
+        // eslint-disable-next-line security/detect-object-injection -- Key normalized from Object.entries iteration
         const requestValue = normalizedRequest[normalizedKey];
         if (!requestValue || !matchesValue(requestValue, value)) {
             return false;
@@ -391,6 +472,7 @@ const matchesHeaders = (requestHeaders, criteriaHeaders) => {
 const matchesQuery = (requestQuery, criteriaQuery) => {
     // Check all required query params exist with exact matching values
     for (const [key, value] of Object.entries(criteriaQuery)) {
+        // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
         const requestValue = requestQuery[key];
         if (!requestValue || !matchesValue(requestValue, value)) {
             return false;

package/dist/domain/scenario-manager.d.ts

@@ -1,4 +1,4 @@
-import type { ScenarioManager, ScenarioRegistry, ScenarioStore, SequenceTracker, StateManager } from "../ports/index.js";
+import type { ScenarioManager, ScenarioRegistry, ScenarioStore, SequenceTracker, StateManager, Logger } from "../ports/index.js";
 /**
  * Factory function to create a ScenarioManager implementation.
  *
@@ -8,13 +8,15 @@ import type { ScenarioManager, ScenarioRegistry, ScenarioStore, SequenceTracker,
  * - Any registry implementation (in-memory, Redis, files, remote)
  * - Any store implementation (in-memory, Redis, database)
  * - Any state manager implementation (in-memory, Redis, database)
+ * - Any logger implementation (console, file, remote)
  * - Proper testing with mock dependencies
  * - True hexagonal architecture
  */
-export declare const createScenarioManager: ({ registry, store, stateManager, sequenceTracker, }: {
+export declare const createScenarioManager: ({ registry, store, stateManager, sequenceTracker, logger, }: {
     registry: ScenarioRegistry;
     store: ScenarioStore;
     stateManager?: StateManager;
     sequenceTracker?: SequenceTracker;
+    logger?: Logger;
 }) => ScenarioManager;
 //# sourceMappingURL=scenario-manager.d.ts.map

package/dist/domain/scenario-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scenario-manager.d.ts","sourceRoot":"","sources":["../../src/domain/scenario-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,YAAY,EACb,MAAM,mBAAmB,CAAC;AAkC3B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GAAI,qDAKnC;IACD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,KAAG,eAgFH,CAAC"}
+{"version":3,"file":"scenario-manager.d.ts","sourceRoot":"","sources":["../../src/domain/scenario-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,MAAM,EACP,MAAM,mBAAmB,CAAC;AAwC3B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAAI,6DAMnC;IACD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,KAAG,eAwHH,CAAC"}

package/dist/domain/scenario-manager.js

@@ -1,24 +1,25 @@
+import { noOpLogger } from "../adapters/index.js";
 import { ScenaristScenarioSchema } from "../schemas/index.js";
-class ScenarioNotFoundError extends Error {
-    constructor(scenarioId) {
-        super(`Scenario '${scenarioId}' not found. Did you forget to register it?`);
-        this.name = "ScenarioNotFoundError";
-    }
-}
-class DuplicateScenarioError extends Error {
-    constructor(scenarioId) {
-        super(`Scenario '${scenarioId}' is already registered. Each scenario must have a unique ID.`);
-        this.name = "DuplicateScenarioError";
-    }
-}
-class ScenarioValidationError extends Error {
-    validationErrors;
-    constructor(message, validationErrors) {
-        super(message);
-        this.validationErrors = validationErrors;
-        this.name = "ScenarioValidationError";
-    }
-}
+import { ScenaristError, ErrorCodes } from "../types/errors.js";
+import { LogCategories, LogEvents } from "./log-events.js";
+const createDuplicateScenarioError = (scenarioId) => {
+    return new ScenaristError(`Scenario '${scenarioId}' is already registered. Each scenario must have a unique ID.`, {
+        code: ErrorCodes.DUPLICATE_SCENARIO,
+        context: {
+            scenarioId,
+            hint: "Use a different scenario ID, or remove the existing scenario before registering a new one.",
+        },
+    });
+};
+const createScenarioValidationError = (scenarioId, validationErrors) => {
+    return new ScenaristError(`Invalid scenario definition for '${scenarioId}': ${validationErrors.join(", ")}`, {
+        code: ErrorCodes.VALIDATION_ERROR,
+        context: {
+            scenarioId,
+            hint: `Check your scenario definition. Validation errors: ${validationErrors.join("; ")}`,
+        },
+    });
+};
 /**
  * Factory function to create a ScenarioManager implementation.
  *
@@ -28,10 +29,11 @@ class ScenarioValidationError extends Error {
  * - Any registry implementation (in-memory, Redis, files, remote)
  * - Any store implementation (in-memory, Redis, database)
  * - Any state manager implementation (in-memory, Redis, database)
+ * - Any logger implementation (console, file, remote)
  * - Proper testing with mock dependencies
  * - True hexagonal architecture
  */
-export const createScenarioManager = ({ registry, store, stateManager, sequenceTracker, }) => {
+export const createScenarioManager = ({ registry, store, stateManager, sequenceTracker, logger = noOpLogger, }) => {
     return {
         registerScenario(definition) {
             // Validate scenario definition at trust boundary
@@ -39,7 +41,7 @@ export const createScenarioManager = ({ registry, store, stateManager, sequenceT
             if (!validationResult.success) {
                 const errorMessages = validationResult.error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
                 const scenarioId = definition?.id || "<unknown>";
-                throw new ScenarioValidationError(`Invalid scenario definition for '${scenarioId}': ${errorMessages.join(", ")}`, errorMessages);
+                throw createScenarioValidationError(scenarioId, errorMessages);
             }
             const existing = registry.get(definition.id);
             // Allow re-registering the exact same scenario object (idempotent)
@@ -48,16 +50,30 @@ export const createScenarioManager = ({ registry, store, stateManager, sequenceT
             }
             // Prevent registering a different scenario with the same ID
             if (existing) {
-                throw new DuplicateScenarioError(definition.id);
+                throw createDuplicateScenarioError(definition.id);
             }
             registry.register(definition);
+            logger.debug(LogCategories.SCENARIO, LogEvents.SCENARIO_REGISTERED, {}, {
+                scenarioId: definition.id,
+                mockCount: definition.mocks.length, // mocks is required by ScenaristScenarioSchema
+            });
         },
         switchScenario(testId, scenarioId) {
             const definition = registry.get(scenarioId);
             if (!definition) {
+                logger.error(LogCategories.SCENARIO, LogEvents.SCENARIO_NOT_FOUND, { testId }, {
+                    requestedScenarioId: scenarioId,
+                });
                 return {
                     success: false,
-                    error: new ScenarioNotFoundError(scenarioId),
+                    error: new ScenaristError(`Scenario '${scenarioId}' not found. Did you forget to register it?`, {
+                        code: ErrorCodes.SCENARIO_NOT_FOUND,
+                        context: {
+                            testId,
+                            scenarioId,
+                            hint: "Make sure to register the scenario before switching to it. Use manager.registerScenario(definition) first.",
+                        },
+                    }),
                 };
             }
             const activeScenario = {
@@ -72,6 +88,7 @@ export const createScenarioManager = ({ registry, store, stateManager, sequenceT
             if (stateManager) {
                 stateManager.reset(testId);
             }
+            logger.info(LogCategories.SCENARIO, LogEvents.SCENARIO_SWITCHED, { testId, scenarioId }, {});
             return { success: true, data: undefined };
         },
         getActiveScenario(testId) {
@@ -82,6 +99,7 @@ export const createScenarioManager = ({ registry, store, stateManager, sequenceT
         },
         clearScenario(testId) {
             store.delete(testId);
+            logger.debug(LogCategories.SCENARIO, LogEvents.SCENARIO_CLEARED, { testId }, {});
         },
         getScenarioById(id) {
             return registry.get(id);

package/dist/domain/state-condition-evaluator.js

@@ -32,6 +32,7 @@ const stateMatchesCondition = (state, when) => {
         if (!(key in state)) {
             return false;
         }
+        // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
         const actualValue = state[key];
         if (!deepEquals(actualValue, expectedValue)) {
             return false;

package/dist/domain/template-replacement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-replacement.d.ts","sourceRoot":"","sources":["../../src/domain/template-replacement.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,OAAO,EACd,cAAc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACpC,OA8DF,CAAC"}
+{"version":3,"file":"template-replacement.d.ts","sourceRoot":"","sources":["../../src/domain/template-replacement.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,OAAO,EACd,cAAc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACpC,OA+DF,CAAC"}

package/dist/domain/template-replacement.js

@@ -49,6 +49,7 @@ export const applyTemplates = (value, templateData) => {
     if (typeof value === "object" && value !== null) {
         const result = {};
         for (const [key, val] of Object.entries(value)) {
+            // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
             result[key] = applyTemplates(val, normalizedData);
         }
         return result;
@@ -67,6 +68,7 @@ export const applyTemplates = (value, templateData) => {
  */
 const resolveTemplatePath = (templateData, prefix, path) => {
     // Get the root object (state or params)
+    // eslint-disable-next-line security/detect-object-injection -- Prefix validated as 'state' or 'params' by regex
     const root = templateData[prefix];
     // Guard: Prefix doesn't exist (e.g., no params provided)
     if (root === undefined || typeof root !== "object" || root === null) {
@@ -86,6 +88,7 @@ const resolveTemplatePath = (templateData, prefix, path) => {
         }
         // Traverse object
         const record = current;
+        // eslint-disable-next-line security/detect-object-injection -- Segment from split() iteration
         current = record[segment];
         // Guard: Return undefined if property doesn't exist
         if (current === undefined) {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type * from "./types/index.js";
+export { ScenaristError, ErrorCodes } from "./types/errors.js";
 export * from "./schemas/index.js";
 export * from "./constants/index.js";
 export type * from "./ports/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,kBAAkB,CAAC;AAGtC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,sBAAsB,CAAC;AAGrC,mBAAmB,kBAAkB,CAAC;AAGtC,mBAAmB,sBAAsB,CAAC;AAG1C,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,kBAAkB,CAAC;AAGtC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/D,cAAc,oBAAoB,CAAC;AAGnC,cAAc,sBAAsB,CAAC;AAGrC,mBAAmB,kBAAkB,CAAC;AAGtC,mBAAmB,sBAAsB,CAAC;AAG1C,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
+// Error classes and constants (runtime values, not just types)
+export { ScenaristError, ErrorCodes } from "./types/errors.js";
 // Schemas (runtime validation)
 export * from "./schemas/index.js";
 // Constants

package/dist/ports/driven/logger.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Log levels ordered by verbosity (ascending).
+ * Each level includes all less verbose levels.
+ *
+ * - silent: No output (production default)
+ * - error: Critical failures preventing operation
+ * - warn: Potential issues that may cause problems
+ * - info: Operation flow and key events
+ * - debug: Detailed decision logic
+ * - trace: Request/response bodies, verbose details
+ */
+export type LogLevel = "silent" | "error" | "warn" | "info" | "debug" | "trace";
+/**
+ * Log categories for filtering specific areas of concern.
+ * Users can enable/disable categories independently.
+ */
+export type LogCategory = "lifecycle" | "scenario" | "matching" | "sequence" | "state" | "template" | "request";
+/**
+ * Base context included in all log events.
+ * Enables filtering and correlation by test ID.
+ */
+export type LogContext = {
+    readonly testId?: string;
+    readonly scenarioId?: string;
+    readonly requestUrl?: string;
+    readonly requestMethod?: string;
+};
+/**
+ * Structured log entry for capture and serialization.
+ */
+export type LogEntry = {
+    readonly level: Exclude<LogLevel, "silent">;
+    readonly category: LogCategory;
+    readonly message: string;
+    readonly context: LogContext;
+    readonly data?: Record<string, unknown>;
+    readonly timestamp: number;
+};
+/**
+ * Logger port for structured logging.
+ *
+ * This is a driven (secondary) port - domain logic calls out to it,
+ * implementations are injected via dependency injection.
+ *
+ * Implementations must handle:
+ * - Level filtering (only emit logs at or above configured level)
+ * - Category filtering (optionally filter by category)
+ * - Output formatting (console, JSON, custom)
+ *
+ * This port enables:
+ * - NoOpLogger: Zero overhead when disabled (production, silent mode)
+ * - ConsoleLogger: Human-readable or JSON output (development)
+ * - TestLogger: Capture logs for assertion in tests
+ * - Custom loggers: User-provided implementations (Winston, Pino, etc.)
+ *
+ * All methods return void - logging is fire-and-forget.
+ * Implementations should never throw.
+ */
+export interface Logger {
+    /**
+     * Log at error level - critical failures preventing operation.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation (testId, scenarioId, etc.)
+     * @param data - Optional structured data for the event
+     */
+    error(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Log at warn level - potential issues that may cause problems.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation
+     * @param data - Optional structured data for the event
+     */
+    warn(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Log at info level - operation flow and key events.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation
+     * @param data - Optional structured data for the event
+     */
+    info(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Log at debug level - detailed decision logic.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation
+     * @param data - Optional structured data for the event
+     */
+    debug(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Log at trace level - request/response bodies, verbose details.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation
+     * @param data - Optional structured data for the event
+     */
+    trace(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Check if a specific level would be logged.
+     * Enables conditional expensive operations before logging.
+     *
+     * @example
+     * if (logger.isEnabled('trace')) {
+     *   logger.trace('request', 'body', ctx, { body: JSON.stringify(large) });
+     * }
+     *
+     * @param level - The log level to check
+     * @returns true if logging at this level is enabled
+     */
+    isEnabled(level: Exclude<LogLevel, "silent">): boolean;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/ports/driven/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/ports/driven/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEhF;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,UAAU,GACV,UAAU,GACV,UAAU,GACV,OAAO,GACP,UAAU,GACV,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;;;OAOG;IACH,KAAK,CACH,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,IAAI,CACF,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,IAAI,CACF,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,KAAK,CACH,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,KAAK,CACH,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC;CACxD"}

package/dist/ports/driven/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/driven/response-selector.d.ts

@@ -1,6 +1,8 @@
 import type { ScenaristMockWithParams, ScenaristResponse, HttpRequestContext, ScenaristResult } from "../../types/index.js";
+import { ScenaristError } from "../../types/errors.js";
 /**
  * Error type for response selection failures.
+ * @deprecated Use ScenaristError with ErrorCodes.NO_MOCK_FOUND instead
  */
 export declare class ResponseSelectionError extends Error {
     constructor(message: string);
@@ -29,6 +31,6 @@ export interface ResponseSelector {
      * @param mocks - Candidate mocks with extracted params (already filtered by URL/method)
      * @returns ScenaristResult with selected ScenaristResponse or error if no match found
      */
-    selectResponse(testId: string, scenarioId: string, context: HttpRequestContext, mocks: ReadonlyArray<ScenaristMockWithParams>): ScenaristResult<ScenaristResponse, ResponseSelectionError>;
+    selectResponse(testId: string, scenarioId: string, context: HttpRequestContext, mocks: ReadonlyArray<ScenaristMockWithParams>): ScenaristResult<ScenaristResponse, ScenaristError>;
 }
 //# sourceMappingURL=response-selector.d.ts.map

package/dist/ports/driven/response-selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response-selector.d.ts","sourceRoot":"","sources":["../../../src/ports/driven/response-selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,aAAa,CAAC,uBAAuB,CAAC,GAC5C,eAAe,CAAC,iBAAiB,EAAE,sBAAsB,CAAC,CAAC;CAC/D"}
+{"version":3,"file":"response-selector.d.ts","sourceRoot":"","sources":["../../../src/ports/driven/response-selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,aAAa,CAAC,uBAAuB,CAAC,GAC5C,eAAe,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAC;CACvD"}

package/dist/ports/driven/response-selector.js

@@ -1,5 +1,6 @@
 /**
  * Error type for response selection failures.
+ * @deprecated Use ScenaristError with ErrorCodes.NO_MOCK_FOUND instead
  */
 export class ResponseSelectionError extends Error {
     constructor(message) {

package/dist/ports/index.d.ts

@@ -5,4 +5,5 @@ export type { RequestContext } from "./driven/request-context.js";
 export type { ResponseSelector } from "./driven/response-selector.js";
 export type { SequenceTracker, SequencePosition, } from "./driven/sequence-tracker.js";
 export type { StateManager } from "./driven/state-manager.js";
+export type { Logger, LogLevel, LogCategory, LogContext, LogEntry, } from "./driven/logger.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/ports/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,YAAY,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,YAAY,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,YAAY,EACV,MAAM,EACN,QAAQ,EACR,WAAW,EACX,UAAU,EACV,QAAQ,GACT,MAAM,oBAAoB,CAAC"}

package/dist/types/config.d.ts

@@ -1,4 +1,24 @@
 import type { ScenaristScenarios } from "./scenario.js";
+/**
+ * How errors should be handled when they occur.
+ *
+ * - `throw`: Throw ScenaristError (strict - test fails with clear message)
+ * - `warn`: Log at warn level, return undefined (let strictMode decide next step)
+ * - `ignore`: Return undefined silently (let strictMode decide next step)
+ */
+export type ErrorBehavior = "throw" | "warn" | "ignore";
+/**
+ * Configuration for how different error types should be handled.
+ * Default is 'throw' for all (strict by default).
+ */
+export type ErrorBehaviors = {
+    /** How to handle when no mock matches a request. Default: 'throw' */
+    readonly onNoMockFound: ErrorBehavior;
+    /** How to handle when a sequence is exhausted. Default: 'throw' */
+    readonly onSequenceExhausted: ErrorBehavior;
+    /** How to handle when x-scenarist-test-id header is missing. Default: 'throw' */
+    readonly onMissingTestId: ErrorBehavior;
+};
 /**
  * Configuration for the scenario management system.
  * All properties are readonly for immutability.
@@ -35,6 +55,11 @@ export type ScenaristConfig = {
      * The default test ID to use when no x-scenarist-test-id header is present.
      */
     readonly defaultTestId: string;
+    /**
+     * How different error types should be handled.
+     * Default is 'throw' for all (strict by default).
+     */
+    readonly errorBehaviors: ErrorBehaviors;
 };
 /**
  * Partial config for user input - missing values will use defaults.
@@ -66,5 +91,9 @@ export type ScenaristConfigInput<T extends ScenaristScenarios = ScenaristScenari
      */
     readonly scenarios: T;
     readonly defaultTestId?: string;
+    /**
+     * Optional error behavior overrides. Missing values use 'throw' as default.
+     */
+    readonly errorBehaviors?: Partial<ErrorBehaviors>;
 };
 //# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE;QAClB,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAC9B,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IAC/C;IACF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,mEAAmE;IACnE,QAAQ,CAAC,mBAAmB,EAAE,aAAa,CAAC;IAC5C,iFAAiF;IACjF,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE;QAClB,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,kEAAkE;QAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAC9B,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IAC/C;IACF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CACnD,CAAC"}