@scenarist/core 0.1.16 → 0.2.1

package/dist/adapters/in-memory-state-manager.d.ts

@@ -12,6 +12,7 @@ export declare class InMemoryStateManager implements StateManager {
     set(testId: string, key: string, value: unknown): void;
     getAll(testId: string): Record<string, unknown>;
     reset(testId: string): void;
+    merge(testId: string, partial: Record<string, unknown>): void;
     private getOrCreateTestState;
     private setNestedValue;
     private getNestedValue;

package/dist/adapters/in-memory-state-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory-state-manager.d.ts","sourceRoot":"","sources":["../../src/adapters/in-memory-state-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAMrE;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IAEtE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAUzC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAyBtD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI/C,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3B,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,cAAc;IAwCtB,OAAO,CAAC,cAAc;CA4BvB;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,QAAO,YAE7C,CAAC"}
+{"version":3,"file":"in-memory-state-manager.d.ts","sourceRoot":"","sources":["../../src/adapters/in-memory-state-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAMrE;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IAEtE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAUzC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAyBtD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI/C,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3B,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAgB7D,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,cAAc;IAwCtB,OAAO,CAAC,cAAc;CA4BvB;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,QAAO,YAE7C,CAAC"}

package/dist/adapters/in-memory-state-manager.js

@@ -43,6 +43,20 @@ export class InMemoryStateManager {
     reset(testId) {
         this.storage.delete(testId);
     }
+    merge(testId, partial) {
+        const currentState = this.getOrCreateTestState(testId);
+        // Filter out dangerous keys and shallow merge
+        for (const [key, value] of Object.entries(partial)) {
+            if (!isDangerousKey(key)) {
+                Object.defineProperty(currentState, key, {
+                    value,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+        }
+    }
     getOrCreateTestState(testId) {
         let testState = this.storage.get(testId);
         if (!testState) {

package/dist/domain/deep-equals.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Deep equality comparison for values.
+ *
+ * Supports primitives, null, undefined, arrays, and objects.
+ * Used for state matching in stateResponse conditions and match.state criteria.
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns true if values are deeply equal, false otherwise
+ */
+export declare const deepEquals: (a: unknown, b: unknown) => boolean;
+//# sourceMappingURL=deep-equals.d.ts.map

package/dist/domain/deep-equals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-equals.d.ts","sourceRoot":"","sources":["../../src/domain/deep-equals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAkEnD,CAAC"}

package/dist/domain/deep-equals.js

@@ -0,0 +1,62 @@
+/**
+ * Deep equality comparison for values.
+ *
+ * Supports primitives, null, undefined, arrays, and objects.
+ * Used for state matching in stateResponse conditions and match.state criteria.
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns true if values are deeply equal, false otherwise
+ */
+export const deepEquals = (a, b) => {
+    // Handle primitives and reference equality
+    if (a === b) {
+        return true;
+    }
+    // Handle null (after === check, if either is null, they're not equal)
+    if (a === null || b === null) {
+        return false;
+    }
+    // Handle undefined
+    if (a === undefined || b === undefined) {
+        return false;
+    }
+    // Handle different types
+    if (typeof a !== typeof b) {
+        return false;
+    }
+    // Handle arrays
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEquals(a[i], b[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    // Handle array vs non-array (one is array, other is object)
+    if (Array.isArray(a) !== Array.isArray(b)) {
+        return false;
+    }
+    // Handle objects
+    if (typeof a === "object" && typeof b === "object") {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length) {
+            return false;
+        }
+        for (const key of aKeys) {
+            if (!(key in b)) {
+                return false;
+            }
+            if (!deepEquals(a[key], b[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+};

package/dist/domain/index.d.ts

@@ -2,4 +2,7 @@ export { createScenarioManager } from "./scenario-manager.js";
 export { buildConfig } from "./config-builder.js";
 export { createResponseSelector } from "./response-selector.js";
 export { matchesRegex } from "./regex-matching.js";
+export { createStateConditionEvaluator, type StateConditionEvaluator, } from "./state-condition-evaluator.js";
+export { createStateResponseResolver, type StateResponseResolver, } from "./state-response-resolver.js";
+export { deepEquals } from "./deep-equals.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EACL,6BAA6B,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/domain/index.js

@@ -2,3 +2,6 @@ export { createScenarioManager } from "./scenario-manager.js";
 export { buildConfig } from "./config-builder.js";
 export { createResponseSelector } from "./response-selector.js";
 export { matchesRegex } from "./regex-matching.js";
+export { createStateConditionEvaluator, } from "./state-condition-evaluator.js";
+export { createStateResponseResolver, } from "./state-response-resolver.js";
+export { deepEquals } from "./deep-equals.js";

package/dist/domain/response-selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response-selector.d.ts","sourceRoot":"","sources":["../../src/domain/response-selector.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,YAAY,EACb,MAAM,mBAAmB,CAAC;AAa3B;;GAEG;AACH,KAAK,6BAA6B,GAAG;IACnC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAS,6BAAkC,KAC1C,gBAiIF,CAAC"}
+{"version":3,"file":"response-selector.d.ts","sourceRoot":"","sources":["../../src/domain/response-selector.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,YAAY,EACb,MAAM,mBAAmB,CAAC;AAe3B;;GAEG;AACH,KAAK,6BAA6B,GAAG;IACnC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAS,6BAAkC,KAC1C,gBAyIF,CAAC"}

package/dist/domain/response-selector.js

@@ -2,6 +2,8 @@ import { ResponseSelectionError } from "../ports/driven/response-selector.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";
 const SPECIFICITY_RANGES = {
     MATCH_CRITERIA_BASE: 100,
     SEQUENCE_FALLBACK: 1,
@@ -38,7 +40,7 @@ export const createResponseSelector = (options = {}) => {
                 // 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)) {
+                    if (matchesCriteria(context, mock.match, testId, stateManager)) {
                         // Match criteria always have higher priority than fallbacks
                         // Base specificity ensures even 1 field beats any fallback
                         const specificity = SPECIFICITY_RANGES.MATCH_CRITERIA_BASE +
@@ -53,9 +55,10 @@ 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
+                // 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,8 +76,8 @@ export const createResponseSelector = (options = {}) => {
             if (bestMatch) {
                 const { mockWithParams, mockIndex } = bestMatch;
                 const mock = mockWithParams.mock;
-                // Select response (either single or from sequence)
-                const response = selectResponseFromMock(testId, scenarioId, mockIndex, mock, sequenceTracker);
+                // Select response (single, sequence, or stateResponse)
+                const response = selectResponseFromMock(testId, scenarioId, mockIndex, mock, sequenceTracker, stateManager);
                 if (!response) {
                     return {
                         success: false,
@@ -97,6 +100,10 @@ export const createResponseSelector = (options = {}) => {
                     };
                     finalResponse = applyTemplates(response, templateData);
                 }
+                // Apply afterResponse.setState to mutate state for subsequent requests
+                if (mock.afterResponse?.setState && stateManager) {
+                    stateManager.merge(testId, mock.afterResponse.setState);
+                }
                 return { success: true, data: finalResponse };
             }
             // No mock matched
@@ -108,16 +115,17 @@ export const createResponseSelector = (options = {}) => {
     };
 };
 /**
- * Select a response from a mock (either single response or from sequence).
+ * Select a response from a mock (single response, sequence, or stateResponse).
  *
- * @param testId - Test ID for sequence tracking
+ * @param testId - Test ID for sequence/state tracking
  * @param scenarioId - Scenario ID for sequence tracking
  * @param mockIndex - Index of the mock in the mocks array
  * @param mock - The mock definition
  * @param sequenceTracker - Optional sequence tracker for Phase 2
- * @returns ScenaristResponse or null if mock has neither response nor sequence
+ * @param stateManager - Optional state manager for stateResponse
+ * @returns ScenaristResponse or null if mock has no response type
  */
-const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTracker) => {
+const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTracker, stateManager) => {
     // Phase 2: If mock has a sequence, use sequence tracker
     if (mock.sequence) {
         if (!sequenceTracker) {
@@ -135,13 +143,39 @@ const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTra
         sequenceTracker.advance(testId, scenarioId, mockIndex, mock.sequence.responses.length, repeatMode);
         return response;
     }
+    // State-aware response: evaluate conditions against current state
+    if (mock.stateResponse) {
+        return resolveStateResponse(testId, mock.stateResponse, stateManager);
+    }
     // Phase 1: Single response
     if (mock.response) {
         return mock.response;
     }
-    // Neither response nor sequence defined
+    // No response type defined
     return null;
 };
+/**
+ * Resolve a stateResponse configuration to a single response.
+ *
+ * Uses the StateResponseResolver to evaluate conditions against
+ * current test state and return the appropriate response.
+ *
+ * @param testId - Test ID for state isolation
+ * @param stateResponse - The stateResponse configuration
+ * @param stateManager - Optional state manager for state lookup
+ * @returns The resolved response (matching condition or default)
+ */
+const resolveStateResponse = (testId, stateResponse, stateManager) => {
+    // Without stateManager, always return default
+    if (!stateManager) {
+        return stateResponse.default;
+    }
+    // Get current state for this test
+    const currentState = stateManager.getAll(testId);
+    // Create resolver and evaluate conditions
+    const resolver = createStateResponseResolver();
+    return resolver.resolveResponse(stateResponse, currentState);
+};
 /**
  * Calculate specificity score for match criteria.
  * Higher score = more specific match.
@@ -151,11 +185,13 @@ const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTra
  * - Each body field = +1 point
  * - Each header = +1 point
  * - Each query param = +1 point
+ * - Each state key = +1 point
  *
  * Example:
  * { body: { itemType: 'premium' } } = 1 point
  * { body: { itemType: 'premium', quantity: 5 }, headers: { 'x-tier': 'gold' } } = 3 points
  * { url: '/api/products', body: { itemType: 'premium' } } = 2 points
+ * { state: { step: 'reviewed', approved: true } } = 2 points
  */
 const calculateSpecificity = (criteria) => {
     let score = 0;
@@ -171,13 +207,21 @@ const calculateSpecificity = (criteria) => {
     if (criteria.query) {
         score += Object.keys(criteria.query).length;
     }
+    if (criteria.state) {
+        score += Object.keys(criteria.state).length;
+    }
     return score;
 };
 /**
  * Check if request context matches the specified criteria.
  * All specified criteria must match for the overall match to succeed.
+ *
+ * @param context - HTTP request context
+ * @param criteria - Match criteria from mock definition
+ * @param testId - Test ID for state isolation
+ * @param stateManager - Optional state manager for state-based matching
  */
-const matchesCriteria = (context, criteria) => {
+const matchesCriteria = (context, criteria, testId, stateManager) => {
     // Check URL match (exact match or pattern)
     if (criteria.url) {
         if (!matchesValue(context.url, criteria.url)) {
@@ -202,9 +246,42 @@ const matchesCriteria = (context, criteria) => {
             return false;
         }
     }
+    // Check state match (partial match on current test state)
+    if (criteria.state) {
+        if (!matchesState(criteria.state, testId, stateManager)) {
+            return false;
+        }
+    }
     // All criteria matched
     return true;
 };
+/**
+ * Check if current test state matches the specified state criteria.
+ * All keys in criteria must exist in state with equal values (partial match).
+ *
+ * @param stateCriteria - Required state key-value pairs
+ * @param testId - Test ID for state isolation
+ * @param stateManager - State manager to retrieve current state
+ * @returns true if all criteria keys match, false otherwise
+ */
+const matchesState = (stateCriteria, testId, stateManager) => {
+    // Without stateManager, state matching always fails
+    if (!stateManager) {
+        return false;
+    }
+    const currentState = stateManager.getAll(testId);
+    // All keys in criteria must exist in state with equal values
+    for (const [key, expectedValue] of Object.entries(stateCriteria)) {
+        if (!(key in currentState)) {
+            return false;
+        }
+        // Deep equality check for values (handles primitives, null, objects)
+        if (!deepEquals(currentState[key], expectedValue)) {
+            return false;
+        }
+    }
+    return true;
+};
 /**
  * Check if request body contains all required fields (partial match).
  * Request can have additional fields beyond what's specified in criteria.

package/dist/domain/state-condition-evaluator.d.ts

@@ -0,0 +1,28 @@
+import type { StateCondition } from "../schemas/state-aware-mocking.js";
+/**
+ * StateConditionEvaluator port for evaluating stateResponse conditions.
+ *
+ * Evaluates conditions against current test state using:
+ * - Partial matching: condition keys must exist in state with matching values
+ * - Specificity-based selection: most specific matching condition wins
+ * - Deep equality: objects/arrays compared structurally
+ */
+export type StateConditionEvaluator = {
+    /**
+     * Find the matching condition based on current state.
+     *
+     * Applies specificity-based selection:
+     * - More specific conditions (more keys) take precedence
+     * - On equal specificity, first matching condition wins
+     *
+     * @param conditions - Array of conditions to evaluate
+     * @param currentState - Current test state to match against
+     * @returns Matching condition or undefined if no match
+     */
+    findMatchingCondition(conditions: ReadonlyArray<StateCondition>, currentState: Readonly<Record<string, unknown>>): StateCondition | undefined;
+};
+/**
+ * Factory function for creating StateConditionEvaluator.
+ */
+export declare const createStateConditionEvaluator: () => StateConditionEvaluator;
+//# sourceMappingURL=state-condition-evaluator.d.ts.map

package/dist/domain/state-condition-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-condition-evaluator.d.ts","sourceRoot":"","sources":["../../src/domain/state-condition-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAGxE;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;;;;;;;OAUG;IACH,qBAAqB,CACnB,UAAU,EAAE,aAAa,CAAC,cAAc,CAAC,EACzC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC9C,cAAc,GAAG,SAAS,CAAC;CAC/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B,QAAO,uBA4BhD,CAAC"}

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

@@ -0,0 +1,41 @@
+import { deepEquals } from "./deep-equals.js";
+/**
+ * Factory function for creating StateConditionEvaluator.
+ */
+export const createStateConditionEvaluator = () => {
+    return {
+        findMatchingCondition(conditions, currentState) {
+            let bestMatch;
+            let bestSpecificity = -1;
+            for (const condition of conditions) {
+                const matches = stateMatchesCondition(currentState, condition.when);
+                if (!matches) {
+                    continue;
+                }
+                const specificity = Object.keys(condition.when).length;
+                // Keep if more specific than current best
+                if (specificity > bestSpecificity) {
+                    bestMatch = condition;
+                    bestSpecificity = specificity;
+                }
+            }
+            return bestMatch;
+        },
+    };
+};
+/**
+ * Check if current state matches a condition's 'when' clause.
+ * All keys in the condition must exist in state with matching values.
+ */
+const stateMatchesCondition = (state, when) => {
+    for (const [key, expectedValue] of Object.entries(when)) {
+        if (!(key in state)) {
+            return false;
+        }
+        const actualValue = state[key];
+        if (!deepEquals(actualValue, expectedValue)) {
+            return false;
+        }
+    }
+    return true;
+};

package/dist/domain/state-response-resolver.d.ts

@@ -0,0 +1,36 @@
+import type { StatefulMockResponse } from "../schemas/state-aware-mocking.js";
+import type { ScenaristResponse } from "../schemas/scenario-definition.js";
+import type { StateConditionEvaluator } from "./state-condition-evaluator.js";
+/**
+ * StateResponseResolver port for resolving stateResponse configurations.
+ *
+ * Resolves which response to return based on current test state:
+ * - Evaluates conditions using StateConditionEvaluator
+ * - Returns matching condition's response or default
+ */
+export type StateResponseResolver = {
+    /**
+     * Resolve the response from a stateResponse configuration.
+     *
+     * @param stateResponse - The stateResponse configuration
+     * @param currentState - Current test state
+     * @returns The resolved response (matching condition or default)
+     */
+    resolveResponse(stateResponse: StatefulMockResponse, currentState: Readonly<Record<string, unknown>>): ScenaristResponse;
+};
+/**
+ * Options for creating a StateResponseResolver.
+ */
+type CreateStateResponseResolverOptions = {
+    /**
+     * Optional custom evaluator for testing.
+     * If not provided, creates a default evaluator.
+     */
+    evaluator?: StateConditionEvaluator;
+};
+/**
+ * Factory function for creating StateResponseResolver.
+ */
+export declare const createStateResponseResolver: (options?: CreateStateResponseResolverOptions) => StateResponseResolver;
+export {};
+//# sourceMappingURL=state-response-resolver.d.ts.map

package/dist/domain/state-response-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-response-resolver.d.ts","sourceRoot":"","sources":["../../src/domain/state-response-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAE3E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;;;OAMG;IACH,eAAe,CACb,aAAa,EAAE,oBAAoB,EACnC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC9C,iBAAiB,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,KAAK,kCAAkC,GAAG;IACxC;;;OAGG;IACH,SAAS,CAAC,EAAE,uBAAuB,CAAC;CACrC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACtC,UAAS,kCAAuC,KAC/C,qBAoBF,CAAC"}

package/dist/domain/state-response-resolver.js

@@ -0,0 +1,16 @@
+import { createStateConditionEvaluator } from "./state-condition-evaluator.js";
+/**
+ * Factory function for creating StateResponseResolver.
+ */
+export const createStateResponseResolver = (options = {}) => {
+    const evaluator = options.evaluator ?? createStateConditionEvaluator();
+    return {
+        resolveResponse(stateResponse, currentState) {
+            const matchingCondition = evaluator.findMatchingCondition(stateResponse.conditions, currentState);
+            if (matchingCondition) {
+                return matchingCondition.then;
+            }
+            return stateResponse.default;
+        },
+    };
+};

package/dist/ports/driven/state-manager.d.ts

@@ -52,5 +52,15 @@ export interface StateManager {
      * @param testId - Test identifier
      */
     reset(testId: string): void;
+    /**
+     * Merge partial state into existing state for a test ID (ADR-0019).
+     *
+     * Performs a shallow merge: `{ ...currentState, ...partial }`.
+     * Used by afterResponse.setState to update test state after mock responses.
+     *
+     * @param testId - Test identifier for state isolation
+     * @param partial - Partial state to merge into existing state
+     */
+    merge(testId: string, partial: Record<string, unknown>): void;
 }
 //# sourceMappingURL=state-manager.d.ts.map

package/dist/ports/driven/state-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../../../src/ports/driven/state-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE1C;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAEvD;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B"}
+{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../../../src/ports/driven/state-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE1C;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAEvD;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/D"}

package/dist/schemas/index.d.ts

@@ -15,4 +15,5 @@ export { ScenarioRequestSchema, type ScenarioRequest, } from "./scenario-request
 export { ScenariosObjectSchema } from "./scenarios-object.js";
 export { HttpMethodSchema, ScenaristResponseSchema, MatchValueSchema, ScenaristMatchSchema, RepeatModeSchema, ScenaristSequenceSchema, ScenaristCaptureConfigSchema, ScenaristUrlPatternSchema, ScenaristMockSchema, ScenaristScenarioSchema, type HttpMethod, type ScenaristResponse, type MatchValue, type ScenaristMatch, type RepeatMode, type ScenaristSequence, type ScenaristCaptureConfig, type ScenaristUrlPattern, type ScenaristMock, type ScenaristScenario, } from "./scenario-definition.js";
 export { SerializedRegexSchema, type SerializedRegex, } from "./match-criteria.js";
+export { StateConditionSchema, StatefulMockResponseSchema, StateAfterResponseSchema, StateMatchCriteriaSchema, type StateCondition, type StatefulMockResponse, type StateAfterResponse, type StateMatchCriteria, } from "./state-aware-mocking.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,4BAA4B,EAC5B,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EAEvB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,4BAA4B,EAC5B,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EAEvB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,0BAA0B,CAAC"}

package/dist/schemas/index.js

@@ -15,3 +15,4 @@ export { ScenarioRequestSchema, } from "./scenario-requests.js";
 export { ScenariosObjectSchema } from "./scenarios-object.js";
 export { HttpMethodSchema, ScenaristResponseSchema, MatchValueSchema, ScenaristMatchSchema, RepeatModeSchema, ScenaristSequenceSchema, ScenaristCaptureConfigSchema, ScenaristUrlPatternSchema, ScenaristMockSchema, ScenaristScenarioSchema, } from "./scenario-definition.js";
 export { SerializedRegexSchema, } from "./match-criteria.js";
+export { StateConditionSchema, StatefulMockResponseSchema, StateAfterResponseSchema, StateMatchCriteriaSchema, } from "./state-aware-mocking.js";

package/dist/schemas/response.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/**
+ * Schema for a scenarist response.
+ *
+ * Extracted to avoid circular dependencies between
+ * scenario-definition.ts and state-aware-mocking.ts.
+ */
+export declare const ScenaristResponseSchema: z.ZodObject<{
+    status: z.ZodNumber;
+    body: z.ZodOptional<z.ZodUnknown>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    delay: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ScenaristResponse = z.infer<typeof ScenaristResponseSchema>;
+//# sourceMappingURL=response.d.ts.map

package/dist/schemas/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/schemas/response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;iBAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/schemas/response.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+/**
+ * Schema for a scenarist response.
+ *
+ * Extracted to avoid circular dependencies between
+ * scenario-definition.ts and state-aware-mocking.ts.
+ */
+export const ScenaristResponseSchema = z.object({
+    status: z.number().int().min(100).max(599),
+    body: z.unknown().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    delay: z.number().nonnegative().optional(),
+});

package/dist/schemas/scenario-definition.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export { ScenaristResponseSchema, type ScenaristResponse } from "./response.js";
 /**
  * Zod schemas for scenario definitions.
  * These schemas validate the structure of scenario data at trust boundaries.
@@ -16,13 +17,6 @@ export declare const HttpMethodSchema: z.ZodEnum<{
     HEAD: "HEAD";
 }>;
 export type HttpMethod = z.infer<typeof HttpMethodSchema>;
-export declare const ScenaristResponseSchema: z.ZodObject<{
-    status: z.ZodNumber;
-    body: z.ZodOptional<z.ZodUnknown>;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    delay: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-export type ScenaristResponse = z.infer<typeof ScenaristResponseSchema>;
 /**
  * Match value supports 6 matching strategies:
  * - Plain string: exact match (backward compatible)
@@ -87,6 +81,7 @@ export declare const ScenaristMatchSchema: z.ZodObject<{
             flags: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>]>>>;
+    state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export type ScenaristMatch = z.infer<typeof ScenaristMatchSchema>;
 export declare const RepeatModeSchema: z.ZodEnum<{
@@ -118,6 +113,12 @@ export type ScenaristCaptureConfig = z.infer<typeof ScenaristCaptureConfigSchema
  */
 export declare const ScenaristUrlPatternSchema: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>]>;
 export type ScenaristUrlPattern = z.infer<typeof ScenaristUrlPatternSchema>;
+/**
+ * ScenaristMock schema with mutual exclusion constraint.
+ *
+ * A mock can have exactly ONE of: response, sequence, or stateResponse.
+ * The afterResponse field can be combined with any of these.
+ */
 export declare const ScenaristMockSchema: z.ZodObject<{
     method: z.ZodEnum<{
         GET: "GET";
@@ -170,6 +171,7 @@ export declare const ScenaristMockSchema: z.ZodObject<{
                 flags: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>]>>>;
+        state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     response: z.ZodOptional<z.ZodObject<{
         status: z.ZodNumber;
@@ -190,7 +192,27 @@ export declare const ScenaristMockSchema: z.ZodObject<{
             none: "none";
         }>>;
     }, z.core.$strip>>;
+    stateResponse: z.ZodOptional<z.ZodObject<{
+        default: z.ZodObject<{
+            status: z.ZodNumber;
+            body: z.ZodOptional<z.ZodUnknown>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            delay: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        conditions: z.ZodArray<z.ZodObject<{
+            when: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            then: z.ZodObject<{
+                status: z.ZodNumber;
+                body: z.ZodOptional<z.ZodUnknown>;
+                headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                delay: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     captureState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    afterResponse: z.ZodOptional<z.ZodObject<{
+        setState: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ScenaristMock = z.infer<typeof ScenaristMockSchema>;
 export declare const ScenaristScenarioSchema: z.ZodObject<{
@@ -249,6 +271,7 @@ export declare const ScenaristScenarioSchema: z.ZodObject<{
                     flags: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
             }, z.core.$strip>]>>>;
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
         response: z.ZodOptional<z.ZodObject<{
             status: z.ZodNumber;
@@ -269,7 +292,27 @@ export declare const ScenaristScenarioSchema: z.ZodObject<{
                 none: "none";
             }>>;
         }, z.core.$strip>>;
+        stateResponse: z.ZodOptional<z.ZodObject<{
+            default: z.ZodObject<{
+                status: z.ZodNumber;
+                body: z.ZodOptional<z.ZodUnknown>;
+                headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                delay: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>;
+            conditions: z.ZodArray<z.ZodObject<{
+                when: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                then: z.ZodObject<{
+                    status: z.ZodNumber;
+                    body: z.ZodOptional<z.ZodUnknown>;
+                    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                    delay: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
         captureState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        afterResponse: z.ZodOptional<z.ZodObject<{
+            setState: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ScenaristScenario = z.infer<typeof ScenaristScenarioSchema>;

package/dist/schemas/scenario-definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scenario-definition.d.ts","sourceRoot":"","sources":["../../src/schemas/scenario-definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;EAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,uBAAuB;;;;;iBAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;mBA4B3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,gBAAgB;;;;EAAoC,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBAGlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,4BAA4B,uCAAmC,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,iEAGpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}
+{"version":3,"file":"scenario-definition.d.ts","sourceRoot":"","sources":["../../src/schemas/scenario-definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,EAAE,uBAAuB,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEhF;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;EAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;mBA4B3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,gBAAgB;;;;EAAoC,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBAGlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,4BAA4B,uCAAmC,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,iEAGpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsB7B,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/schemas/scenario-definition.js

@@ -1,5 +1,9 @@
 import { z } from "zod";
 import { SerializedRegexSchema } from "./match-criteria.js";
+import { ScenaristResponseSchema } from "./response.js";
+import { StatefulMockResponseSchema, StateAfterResponseSchema, } from "./state-aware-mocking.js";
+// Re-export from response.ts (no backward compatibility concerns - no consumers yet)
+export { ScenaristResponseSchema } from "./response.js";
 /**
  * Zod schemas for scenario definitions.
  * These schemas validate the structure of scenario data at trust boundaries.
@@ -16,12 +20,6 @@ export const HttpMethodSchema = z.enum([
     "OPTIONS",
     "HEAD",
 ]);
-export const ScenaristResponseSchema = z.object({
-    status: z.number().int().min(100).max(599),
-    body: z.unknown().optional(),
-    headers: z.record(z.string(), z.string()).optional(),
-    delay: z.number().nonnegative().optional(),
-});
 /**
  * Match value supports 6 matching strategies:
  * - Plain string: exact match (backward compatible)
@@ -64,6 +62,7 @@ export const ScenaristMatchSchema = z.object({
     body: z.record(z.string(), MatchValueSchema).optional(),
     headers: z.record(z.string(), MatchValueSchema).optional(),
     query: z.record(z.string(), MatchValueSchema).optional(),
+    state: z.record(z.string(), z.unknown()).optional(),
 });
 export const RepeatModeSchema = z.enum(["last", "cycle", "none"]);
 export const ScenaristSequenceSchema = z.object({
@@ -80,13 +79,30 @@ export const ScenaristUrlPatternSchema = z.union([
     z.string().min(1),
     z.instanceof(RegExp),
 ]);
-export const ScenaristMockSchema = z.object({
+/**
+ * ScenaristMock schema with mutual exclusion constraint.
+ *
+ * A mock can have exactly ONE of: response, sequence, or stateResponse.
+ * The afterResponse field can be combined with any of these.
+ */
+export const ScenaristMockSchema = z
+    .object({
     method: HttpMethodSchema,
     url: ScenaristUrlPatternSchema,
     match: ScenaristMatchSchema.optional(),
     response: ScenaristResponseSchema.optional(),
     sequence: ScenaristSequenceSchema.optional(),
+    stateResponse: StatefulMockResponseSchema.optional(),
     captureState: ScenaristCaptureConfigSchema.optional(),
+    afterResponse: StateAfterResponseSchema.optional(),
+})
+    .refine((mock) => {
+    const responseTypes = [mock.response, mock.sequence, mock.stateResponse];
+    const definedCount = responseTypes.filter((r) => r !== undefined).length;
+    // Allow 0 (for fallback mocks) or exactly 1
+    return definedCount <= 1;
+}, {
+    message: "A mock can have at most one of: response, sequence, or stateResponse",
 });
 export const ScenaristScenarioSchema = z.object({
     id: z.string().min(1),

package/dist/schemas/scenarios-object.d.ts

@@ -65,6 +65,7 @@ export declare const ScenariosObjectSchema: z.ZodRecord<z.ZodString, z.ZodObject
                     flags: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
             }, z.core.$strip>]>>>;
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
         response: z.ZodOptional<z.ZodObject<{
             status: z.ZodNumber;
@@ -85,7 +86,27 @@ export declare const ScenariosObjectSchema: z.ZodRecord<z.ZodString, z.ZodObject
                 none: "none";
             }>>;
         }, z.core.$strip>>;
+        stateResponse: z.ZodOptional<z.ZodObject<{
+            default: z.ZodObject<{
+                status: z.ZodNumber;
+                body: z.ZodOptional<z.ZodUnknown>;
+                headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                delay: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>;
+            conditions: z.ZodArray<z.ZodObject<{
+                when: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                then: z.ZodObject<{
+                    status: z.ZodNumber;
+                    body: z.ZodOptional<z.ZodUnknown>;
+                    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                    delay: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
         captureState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        afterResponse: z.ZodOptional<z.ZodObject<{
+            setState: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>>;
 //# sourceMappingURL=scenarios-object.d.ts.map

package/dist/schemas/scenarios-object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scenarios-object.d.ts","sourceRoot":"","sources":["../../src/schemas/scenarios-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAI9B,CAAC"}
+{"version":3,"file":"scenarios-object.d.ts","sourceRoot":"","sources":["../../src/schemas/scenarios-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAI9B,CAAC"}

package/dist/schemas/state-aware-mocking.d.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+/**
+ * Zod schemas for state-aware mocking (ADR-0019).
+ *
+ * These schemas define the structure of:
+ * - stateResponse: Conditional responses based on test state
+ * - afterResponse.setState: State mutation after response
+ * - match.state: Mock selection based on current state
+ */
+/**
+ * Schema for a single state condition.
+ *
+ * The `when` clause is a partial match object - all keys must match
+ * the current state for the condition to apply.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   when: { checked: true, step: 'reviewed' },
+ *   then: { status: 200, body: { state: 'approved' } }
+ * }
+ * ```
+ */
+export declare const StateConditionSchema: z.ZodObject<{
+    when: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    then: z.ZodObject<{
+        status: z.ZodNumber;
+        body: z.ZodOptional<z.ZodUnknown>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        delay: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type StateCondition = z.infer<typeof StateConditionSchema>;
+/**
+ * Schema for stateful mock response (stateResponse).
+ *
+ * Returns different responses based on current test state.
+ * Uses specificity-based selection: most specific matching condition wins.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   default: { status: 200, body: { state: 'appStarted' } },
+ *   conditions: [
+ *     { when: { checked: true }, then: { status: 200, body: { state: 'quoteDecline' } } }
+ *   ]
+ * }
+ * ```
+ */
+export declare const StatefulMockResponseSchema: z.ZodObject<{
+    default: z.ZodObject<{
+        status: z.ZodNumber;
+        body: z.ZodOptional<z.ZodUnknown>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        delay: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    conditions: z.ZodArray<z.ZodObject<{
+        when: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        then: z.ZodObject<{
+            status: z.ZodNumber;
+            body: z.ZodOptional<z.ZodUnknown>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            delay: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StatefulMockResponse = z.infer<typeof StatefulMockResponseSchema>;
+/**
+ * Schema for afterResponse configuration.
+ *
+ * The setState object is merged into the current test state after
+ * the response is returned.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   setState: { checked: true, step: 'completed' }
+ * }
+ * ```
+ */
+export declare const StateAfterResponseSchema: z.ZodObject<{
+    setState: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type StateAfterResponse = z.infer<typeof StateAfterResponseSchema>;
+/**
+ * Schema for state matching criteria (used in match.state).
+ *
+ * Partial match - all keys in the match criteria must match
+ * the current state, but state can have additional keys.
+ */
+export declare const StateMatchCriteriaSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type StateMatchCriteria = z.infer<typeof StateMatchCriteriaSchema>;
+//# sourceMappingURL=state-aware-mocking.d.ts.map

package/dist/schemas/state-aware-mocking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-aware-mocking.d.ts","sourceRoot":"","sources":["../../src/schemas/state-aware-mocking.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;GAOG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;iBAO/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;iBAGrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB;;iBAMnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,wCAAoC,CAAC;AAC1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/schemas/state-aware-mocking.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { ScenaristResponseSchema } from "./response.js";
+/**
+ * Zod schemas for state-aware mocking (ADR-0019).
+ *
+ * These schemas define the structure of:
+ * - stateResponse: Conditional responses based on test state
+ * - afterResponse.setState: State mutation after response
+ * - match.state: Mock selection based on current state
+ */
+/**
+ * Schema for a single state condition.
+ *
+ * The `when` clause is a partial match object - all keys must match
+ * the current state for the condition to apply.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   when: { checked: true, step: 'reviewed' },
+ *   then: { status: 200, body: { state: 'approved' } }
+ * }
+ * ```
+ */
+export const StateConditionSchema = z.object({
+    when: z
+        .record(z.string(), z.unknown())
+        .refine((obj) => Object.keys(obj).length > 0, {
+        message: "when clause must have at least one key",
+    }),
+    then: ScenaristResponseSchema,
+});
+/**
+ * Schema for stateful mock response (stateResponse).
+ *
+ * Returns different responses based on current test state.
+ * Uses specificity-based selection: most specific matching condition wins.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   default: { status: 200, body: { state: 'appStarted' } },
+ *   conditions: [
+ *     { when: { checked: true }, then: { status: 200, body: { state: 'quoteDecline' } } }
+ *   ]
+ * }
+ * ```
+ */
+export const StatefulMockResponseSchema = z.object({
+    default: ScenaristResponseSchema,
+    conditions: z.array(StateConditionSchema),
+});
+/**
+ * Schema for afterResponse configuration.
+ *
+ * The setState object is merged into the current test state after
+ * the response is returned.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   setState: { checked: true, step: 'completed' }
+ * }
+ * ```
+ */
+export const StateAfterResponseSchema = z.object({
+    setState: z
+        .record(z.string(), z.unknown())
+        .refine((obj) => Object.keys(obj).length > 0, {
+        message: "setState must have at least one key",
+    }),
+});
+/**
+ * Schema for state matching criteria (used in match.state).
+ *
+ * Partial match - all keys in the match criteria must match
+ * the current state, but state can have additional keys.
+ */
+export const StateMatchCriteriaSchema = z.record(z.string(), z.unknown());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenarist/core",
-  "version": "0.1.16",
+  "version": "0.2.1",
   "description": "Internal: Hexagonal architecture core for scenario-based testing with MSW",
   "author": "Paul Hammond (citypaul) <paul@packsoftware.co.uk>",
   "license": "MIT",