## 1. Integration Surface Inventory & Confidence Assessment | Boundary | Call mode | Contract status | |---|---|---| | **B1** cart-service → order-service (REST) | Synchronous (*Inferred from architecture pattern*: REST request/response; protocol is *Explicit in inputs*) | Implied only. Schema, status codes and timeout behavior are not stated. `<NEEDS-INPUT: rest-contract-b1-b2>` | | **B2** order-service → payment-service (REST) | Synchronous (*Inferred from architecture pattern*) | Implied only. `<NEEDS-INPUT: rest-contract-b1-b2>`, `<NEEDS-INPUT: timeout-and-retry-policy>` | | **B3** payment-service → Stripe API (external, official test-mode) | Synchronous (*Inferred from architecture pattern*). Whether payment confirmation is fully synchronous or relies on webhooks is unstated. `<NEEDS-INPUT: stripe-confirmation-mode>` | Implied only. Stripe publishes its own API contract, but the calls used, the pinned API version and the mapping of Stripe results to payment-service responses are not stated. Test-mode use is *Explicit in inputs*. | | **B4** `order.confirmed` on Kafka → fulfillment-service | Asynchronous (*Inferred from architecture pattern*: Kafka event delivery; the event name and Kafka transport are *Explicit in inputs*) | Implied only. Topic, key, payload schema and delivery guarantees are not stated. `<NEEDS-INPUT: kafka-topic-and-schema>`. The publishing service is not stated. `<NEEDS-INPUT: order-confirmed-publisher>` | **Confidence assessment** - High confidence: service topology and call order of the checkout flow (*Explicit in inputs*). - Medium confidence: synchronous versus asynchronous classification of each boundary (*Inferred from architecture pattern*). - Low confidence: every interface contract and all failure semantics. All four boundaries (B1–B4) are flagged for contract testing in Section 6. - No datastore is named in the inputs. No persistence boundary is tested directly. Order state is observable only through whatever read interface order-service exposes. `<NEEDS-INPUT: order-status-read-endpoint>` - The trigger entry point (how a test submits a checkout to cart-service) is not described. `<NEEDS-INPUT: checkout-endpoint-contract>` ## 2. Critical Flow Mapping **Flow: Checkout** (*Explicit in inputs*: cart-service → order-service → payment-service → fulfillment-service; a failed payment must never result in a fulfillment event being published) 1. Test client submits a checkout request → cart-service (test trigger and entry point, not a listed boundary; `<NEEDS-INPUT: checkout-endpoint-contract>`) 2. cart-service → order-service over REST **[B1]**. SYNCHRONOUS: failure blocks cart-service immediately (*Inferred from architecture pattern*). 3. order-service → payment-service over REST **[B2]**. SYNCHRONOUS: failure or delay blocks order-service (*Inferred from architecture pattern*). 4. payment-service → Stripe test-mode API **[B3]**. SYNCHRONOUS (*Inferred from architecture pattern*; `<NEEDS-INPUT: stripe-confirmation-mode>`). 5. Branch on the Stripe outcome: - 5a. Payment succeeds → `order.confirmed` is published to Kafka **[B4]** (publisher: `<NEEDS-INPUT: order-confirmed-publisher>`) → success response returns up B2 and B1 (*Inferred from architecture pattern*). ASYNCHRONOUS for the publish step: a failure may surface later or silently. - 5b. Payment fails → NO `order.confirmed` event is published (*Explicit in inputs*) → failure response returns up B2 and B1 (*Inferred from architecture pattern*). Resulting order state and response contents: `<NEEDS-INPUT: failed-payment-order-state>`. 6. fulfillment-service consumes `order.confirmed` **[B4]**. ASYNCHRONOUS: a consumer failure is invisible to the checkout caller. The observable effect of fulfillment is `<NEEDS-INPUT: fulfillment-observable-effect>`. **Detection strategy by mode** - Synchronous steps (B1, B2, B3): failure is detected from the response code, body and elapsed time returned to the caller. - Asynchronous publish (step 5a): presence is detected by a test consumer polling with a timeout. Absence (required in 5b) is detected with a bounded observation window plus a positive control, defined in Section 5. - Asynchronous consume (step 6): detected through the fulfillment observable effect, polled with a timeout. ## 3. Scenario Inventory ### Happy path **Successful checkout publishes order.confirmed** - Boundaries: B1, B2, B3, B4. - Trigger: valid cart, Stripe test-mode payment method that succeeds. - Expected: success propagates B3 → B2 → B1 (*Inferred from architecture pattern*). Exactly one `order.confirmed` event is published for the order (*Inferred from architecture pattern*). fulfillment-service consumes it and produces its observable effect (`<NEEDS-INPUT: fulfillment-observable-effect>`). ### Partial failure **Stripe card decline publishes no fulfillment event** - Boundaries: B3, B2, B1, B4. - Trigger: Stripe test-mode payment method that is declined. - Expected: payment-service returns a failure to order-service (*Inferred from architecture pattern*). No `order.confirmed` is published and fulfillment-service performs no action (*Explicit in inputs*). No successful payment exists at Stripe for the order (*Inferred from architecture pattern*). Order state and the response returned to the client: `<NEEDS-INPUT: failed-payment-order-state>`. **Stripe processing error publishes no fulfillment event** - Boundaries: B3, B2, B1, B4. - Trigger: Stripe test-mode payment method that returns a processing error. - Expected: no `order.confirmed` is published (*Explicit in inputs*). Whether payment-service retries the Stripe call or fails immediately: `<NEEDS-INPUT: timeout-and-retry-policy>`. Order state: `<NEEDS-INPUT: failed-payment-order-state>`. **payment-service unavailable at order-service boundary** - Boundaries: B2, B1, B4. - Trigger: connection refused or 5xx from payment-service when order-service calls it. - Expected: order-service does not proceed as if paid, and Stripe is never called (*Inferred from architecture pattern*). No `order.confirmed` is published (*Explicit in inputs*). The error returned to cart-service and any retry: `<NEEDS-INPUT: timeout-and-retry-policy>`. Order state: `<NEEDS-INPUT: failed-payment-order-state>`. **payment-service slow response beyond order-service timeout** - Boundaries: B2, B3, B4. - Trigger: payment-service response delayed beyond order-service's configured timeout, with a Stripe payment that would succeed (exercises the late-success hazard). - Expected: order-service stops waiting per its timeout policy. The required system-wide outcome when payment-service later completes the payment successfully (reconcile, refund, or confirm late) is not stated. `<NEEDS-INPUT: timeout-and-retry-policy>`. Invariant to assert once defined: no state persists in which the customer is charged and no path to fulfillment or refund exists. **order-service slow response beyond cart-service timeout** - Boundaries: B1, B2, B3, B4. - Trigger: order-service response delayed beyond cart-service's configured timeout. - Expected: cart-service returns a defined failure to the client (*Inferred from architecture pattern*). Whether order-service continues processing the checkout after cart-service has given up, and what happens to a successful payment in that case: `<NEEDS-INPUT: timeout-and-retry-policy>`. **Stripe unreachable or timing out from payment-service** - Boundaries: B3, B2, B1, B4. - Trigger: Stripe test-mode API unreachable or not responding within payment-service's timeout. - Expected: payment-service returns a failure to order-service (*Inferred from architecture pattern*). No `order.confirmed` is published (*Explicit in inputs*). Payment outcome is uncertain after a Stripe timeout, so reconciliation behavior is `<NEEDS-INPUT: timeout-and-retry-policy>`. **Kafka publish failure after successful payment** - Boundaries: B3, B4. - Trigger: Stripe payment succeeds, then the publish of `order.confirmed` fails (broker unreachable or rejecting). - Expected: not stated (retry, outbox, refund, or pending order are all plausible). `<NEEDS-INPUT: kafka-publish-failure-behavior>`. The outcome must be observable to the test, not silent. **Duplicate checkout submission** - Boundaries: B1, B2, B3, B4. - Trigger: the same checkout request submitted twice, sequentially and near-concurrently. - Expected: not stated. `<NEEDS-INPUT: idempotency-contract>`. ### Data consistency **order.confirmed payload consistency** - Boundary: B4. - Trigger: successful checkout with a multi-item cart. - Expected: the event's order identifier and order content correspond to the order created through B1 and B2 (*Inferred from architecture pattern*). Field-level schema: `<NEEDS-INPUT: kafka-topic-and-schema>`. fulfillment-service consumes the event and its effect matches the order (`<NEEDS-INPUT: fulfillment-observable-effect>`). **Charged amount matches cart total** - Boundaries: B1, B2, B3. - Trigger: successful checkout with multiple line items and non-trivial rounding. - Expected: the amount and currency on the Stripe test-mode payment equal the order total held by order-service (*Inferred from architecture pattern*). Order total is read via `<NEEDS-INPUT: order-status-read-endpoint>`. Currency and rounding rules: `<NEEDS-INPUT: rest-contract-b1-b2>`. ### Contract drift **Unexpected response shape from payment-service at order-service** - Boundary: B2. - Trigger: payment-service replies with HTTP 200 but the payment status field is missing, has an unrecognized value, has the wrong type, or the body is not JSON. - Expected: order-service does not treat the result as a successful payment (fail-closed, *Inferred from architecture pattern*) and no `order.confirmed` is published. Exact error and order state: `<NEEDS-INPUT: rest-contract-b1-b2>`, `<NEEDS-INPUT: failed-payment-order-state>`. **Unexpected response shape from Stripe at payment-service** - Boundary: B3. - Trigger: Stripe response whose shape differs from what payment-service parses. - Expected: payment-service fails closed and returns a failure to order-service (*Inferred from architecture pattern*). Producing this trigger is subject to `<NEEDS-INPUT: stripe-fault-policy>`. **Unexpected response shape from order-service at cart-service** - Boundary: B1. - Trigger: order-service replies with HTTP 200 but the order identifier is missing, or an error body arrives under a success status, or the body is not JSON. - Expected: cart-service does not report checkout success to the client (*Inferred from architecture pattern*). Exact error: `<NEEDS-INPUT: rest-contract-b1-b2>`. **Malformed order.confirmed event at fulfillment-service** - Boundary: B4. - Trigger: an `order.confirmed` event with a required field missing or a non-conforming payload, followed by a valid event. - Expected: fulfillment-service handles the malformed event by a defined path (skip, dead-letter, or halt) and continues to process the subsequent valid event (*Inferred from architecture pattern*). The defined path: `<NEEDS-INPUT: malformed-event-handling>`. ## 4. Test Environment & Data Strategy Environment (*Explicit in inputs*): one shared staging environment; Stripe calls must use Stripe's official test-mode API, never a mock. ### Feasibility by scenario **Category A: runnable against real staging instances and Stripe test-mode** - **Successful checkout publishes order.confirmed** - **Stripe card decline publishes no fulfillment event** - **Stripe processing error publishes no fulfillment event** - **order.confirmed payload consistency** - **Charged amount matches cart total** - **Duplicate checkout submission** (runnable, but the assertion is undefined until `<NEEDS-INPUT: idempotency-contract>` is resolved) Every Category A scenario also needs Kafka read access for a test consumer (`<NEEDS-INPUT: kafka-test-access>`) and a way to trigger checkout and pass a test-mode payment method (`<NEEDS-INPUT: checkout-endpoint-contract>`, `<NEEDS-INPUT: payment-method-input>`). Stripe is exercised in its official test mode, which satisfies the stated policy. **Category B: require a provider stub (contract-level, not full-chain integration)** - **Unexpected response shape from payment-service at order-service** - **Unexpected response shape from order-service at cart-service** These verify only how the calling service degrades at one boundary. They require a service instance that can be pointed at a stub of its downstream (`<NEEDS-INPUT: fault-injection-and-stubbing>`). Without that ability they move to Category C. They are labeled contract tests and are not counted as end-to-end integration coverage. **Category C: cannot be reliably tested in the available environment as-is** - **payment-service unavailable at order-service boundary**: taking payment-service down or blocking its route in a shared staging environment disrupts other users and needs fault injection that is not confirmed. `<NEEDS-INPUT: fault-injection-and-stubbing>` - **payment-service slow response beyond order-service timeout**: real instances give no control over latency, and the timeout value is unknown. `<NEEDS-INPUT: fault-injection-and-stubbing>`, `<NEEDS-INPUT: timeout-and-retry-policy>` - **order-service slow response beyond cart-service timeout**: same limitation at B1. - **Stripe unreachable or timing out from payment-service**: Stripe test-mode cannot be made slow or unreachable on demand, and a network-level fault or stub in front of Stripe may conflict with the no-mock policy. `<NEEDS-INPUT: stripe-fault-policy>` - **Kafka publish failure after successful payment**: failing the broker in shared staging affects every consumer and producer. `<NEEDS-INPUT: fault-injection-and-stubbing>` - **Unexpected response shape from Stripe at payment-service**: Stripe test-mode returns only real Stripe shapes, and fabricating one is a mock of Stripe. `<NEEDS-INPUT: stripe-fault-policy>` - **Malformed order.confirmed event at fulfillment-service**: producing a malformed event onto a shared topic risks a poison-message effect on other staging users; safe only on an isolated topic or consumer. `<NEEDS-INPUT: malformed-event-handling>` Stubbing any Category C scenario would verify only the calling service's local degradation and would not verify the system-wide consequence (no event published, no charged-but-unfulfilled state). It is therefore not equivalent coverage and is not to be reported as such. ### Data setup and teardown by scenario category - **Happy path and data consistency**: create carts and items namespaced with a per-run `RUN_ID` (in cart or customer identifiers where accepted, and in Stripe test-mode object metadata). Each test creates its own Stripe test-mode payment objects and never reuses them. Teardown cancels uncaptured Stripe test payments and removes or marks test orders. `<NEEDS-INPUT: test-data-seeding-and-teardown>` - **Partial failure**: same namespacing. Fault injections are scoped to `RUN_ID` traffic where possible and are removed in a teardown step that always runs, so no fault outlives its test. - **Contract drift**: stubs are started per test and torn down after it. Stub-driven tests run against an isolated service instance, never against the shared instance other users depend on. - **Kafka**: each test run uses its own unique consumer group. It must never use fulfillment-service's consumer group, or the test consumer would take partitions away from it (*Inferred from architecture pattern*). Events are correlated by order identifier, not by topic position, because the topic carries other staging traffic (`<NEEDS-INPUT: kafka-topic-and-schema>`). ### Building on existing infrastructure (*Explicit in inputs*: Postman/Newman collection covers order-service in isolation; no cross-service suite exists) - Reuse the Newman collection's environment, auth setup and order-service read requests for order-state assertions. Isolated order-service checks are not repeated here. - Newman can drive the REST triggers, but it cannot consume Kafka. A separate harness with a Kafka client is required for event assertions (*Inferred from architecture pattern*). Language and framework are unspecified and left to the team; the outlines in Section 5 are framework-agnostic. - CI integration and scheduling against the shared staging environment: `<NEEDS-INPUT: ci-integration>`. ## 5. Scenario Implementation Outlines **Shared harness conventions** (test-harness parameters, not system behavior) - **H1, consumer readiness**: start the test Kafka consumer with a unique group, wait until partition assignment is confirmed, and record starting offsets before every trigger. A trigger sent before assignment can miss its own event. - **H2, absence check protocol**: after the trigger, hold for `OBSERVE_WINDOW`, then assert zero `order.confirmed` events for the order's correlation key. `OBSERVE_WINDOW = max(3 × the publish latency measured in Successful checkout publishes order.confirmed, 30s)`. Run **Successful checkout publishes order.confirmed** first in the same suite run as the positive control proving the consumer is live. - **H3, async settle**: poll every `POLL_INTERVAL` (default 1s) until `SETTLE_TIMEOUT` (default 60s, tuned after measuring real latency). No fixed sleeps. ### Happy path **Successful checkout publishes order.confirmed** - Setup: seed a `RUN_ID`-namespaced cart with in-stock items; obtain the Stripe test-mode success payment method (test card 4242 4242 4242 4242 per Stripe's public testing documentation; delivery to payment-service per `<NEEDS-INPUT: payment-method-input>`); H1. - Trigger: submit checkout to cart-service (`<NEEDS-INPUT: checkout-endpoint-contract>`). - Assertions: (1) the synchronous response indicates success within the caller's timeout; (2) a Stripe test-mode lookup shows exactly one successful payment tagged with the `RUN_ID` order; (3) H3 poll: exactly one `order.confirmed` for the order's correlation key, and record its publish latency; (4) no second event for the order through `OBSERVE_WINDOW`; (5) H3 poll of the fulfillment observable effect until it appears (`<NEEDS-INPUT: fulfillment-observable-effect>`); (6) order-service reports the confirmed state (`<NEEDS-INPUT: order-status-read-endpoint>`). ### Partial failure **Stripe card decline publishes no fulfillment event** - Setup: as above with the Stripe decline test-mode payment method (test card 4000 0000 0000 0002 per Stripe's public testing documentation); H1. - Trigger: submit checkout. - Assertions: (1) a failure response returns synchronously, with status and body per `<NEEDS-INPUT: failed-payment-order-state>`; (2) Stripe lookup shows no successful payment for the `RUN_ID` order; (3) H2: zero `order.confirmed` for the order; (4) no fulfillment observable effect for the order after `OBSERVE_WINDOW`; (5) order state equals the defined failed state (assertion incomplete until `<NEEDS-INPUT: failed-payment-order-state>` is resolved). **Stripe processing error publishes no fulfillment event** - Setup: as above with the Stripe processing-error test-mode payment method (test card 4000 0000 0000 0119 per Stripe's public testing documentation); H1. - Trigger: submit checkout. - Assertions: (1) failure response per `<NEEDS-INPUT: failed-payment-order-state>`; (2) the number of Stripe payment attempts for the order equals the defined retry policy (`<NEEDS-INPUT: timeout-and-retry-policy>`); (3) H2: zero `order.confirmed`; (4) no fulfillment observable effect. **payment-service unavailable at order-service boundary** (*blocked, not implementation-ready until `<NEEDS-INPUT: fault-injection-and-stubbing>` is resolved*) - Setup: a fault rule that refuses connections from order-service to payment-service, scoped to `RUN_ID` traffic; H1; teardown removes the rule even on failure. - Trigger: submit checkout with the success payment method. - Assertions: (1) failure response within order-service's connect or timeout limit plus margin (`<NEEDS-INPUT: timeout-and-retry-policy>`); (2) no Stripe payment exists for the order; (3) H2: zero `order.confirmed`; (4) order state per `<NEEDS-INPUT: failed-payment-order-state>`. **payment-service slow response beyond order-service timeout** (*blocked, not implementation-ready until `<NEEDS-INPUT: fault-injection-and-stubbing>` and `<NEEDS-INPUT: timeout-and-retry-policy>` are resolved*) - Setup: a latency rule on payment-service responses greater than order-service's timeout, scoped to `RUN_ID` traffic; success payment method; H1; always-run fault teardown. - Trigger: submit checkout. - Assertions: (1) the client response returns within timeout plus margin, in the form defined by policy; (2) after `SETTLE_TIMEOUT`, a Stripe lookup and H2/H3 event checks show one of the policy-defined end states (reconciled with no event, or event only after reconciliation), and never a charged payment with no fulfillment or refund path. **order-service slow response beyond cart-service timeout** (*blocked, not implementation-ready until `<NEEDS-INPUT: fault-injection-and-stubbing>` and `<NEEDS-INPUT: timeout-and-retry-policy>` are resolved*) - Setup: latency rule on order-service responses beyond cart-service's timeout, scoped to `RUN_ID` traffic; success payment method; H1; always-run fault teardown. - Trigger: submit checkout. - Assertions: (1) cart-service returns a defined failure within timeout plus margin; (2) after `SETTLE_TIMEOUT`, Stripe and event checks match the policy-defined end state for a request that cart-service abandoned but order-service may have continued. **Stripe unreachable or timing out from payment-service** (*blocked, not implementation-ready until `<NEEDS-INPUT: stripe-fault-policy>` is resolved*) - Setup: a network-level fault between payment-service and the Stripe test-mode host, if permitted; H1; always-run fault teardown. - Trigger: submit checkout. - Assertions: (1) failure response within payment-service's Stripe timeout plus margin; (2) H2: zero `order.confirmed`; (3) Stripe lookup after `SETTLE_TIMEOUT` shows whether a payment was created despite the timeout, and the outcome matches the reconciliation policy (`<NEEDS-INPUT: timeout-and-retry-policy>`). **Kafka publish failure after successful payment** (*blocked, not implementation-ready until `<NEEDS-INPUT: fault-injection-and-stubbing>` and `<NEEDS-INPUT: kafka-publish-failure-behavior>` are resolved*) - Setup: make publish fail for `RUN_ID` traffic only (for example an ACL or quota on a test topic or producer identity, if available); success payment method; H1. - Trigger: submit checkout. - Assertions: (1) Stripe lookup shows the payment succeeded; (2) after `SETTLE_TIMEOUT`, the end state matches the defined behavior (retry delivers the event, or refund, or explicit pending state), never silent loss; (3) once the fault is removed, no duplicate or orphaned events remain. **Duplicate checkout submission** - Setup: as **Successful checkout publishes order.confirmed**; H1. - Trigger: (a) the identical request twice in sequence; (b) the identical request twice concurrently. Retry-on-failure helpers must not be applied to this trigger. - Assertions (pending `<NEEDS-INPUT: idempotency-contract>`): number of successful Stripe payments for the order(s), number of `order.confirmed` events, number of fulfillment effects, and the second request's response, each compared against the defined contract. ### Data consistency **order.confirmed payload consistency** - Setup: cart with three line items of distinct quantities and prices; success payment method; H1. - Trigger: submit checkout. - Assertions: (1) H3 poll retrieves the event for the order; (2) the payload validates against the event schema (required fields present, types correct; `<NEEDS-INPUT: kafka-topic-and-schema>`); (3) the order identifier equals the one returned through the checkout response; (4) line items and total equal the seeded cart; (5) the fulfillment observable effect reflects the same items (`<NEEDS-INPUT: fulfillment-observable-effect>`). Timestamps, ordering of unrelated fields and other incidental values are not asserted. **Charged amount matches cart total** - Setup: cart with several items whose prices force rounding (per `<NEEDS-INPUT: rest-contract-b1-b2>` for currency rules); success payment method. - Trigger: submit checkout. - Assertions: (1) the order total read from order-service (`<NEEDS-INPUT: order-status-read-endpoint>`) equals the seeded expected total; (2) the Stripe test-mode payment amount (in the smallest currency unit) and currency equal that total; (3) exactly one payment exists for the order. ### Contract drift **Unexpected response shape from payment-service at order-service** (Category B; requires `<NEEDS-INPUT: fault-injection-and-stubbing>`) - Setup: an order-service instance configured to call a stub of payment-service; H1 if that instance publishes to an observable topic. - Trigger: for each variant (status field missing; unrecognized status value; wrong type; non-JSON body), submit checkout to the order-service under test with the stub returning that HTTP 200 body. - Assertions: (1) order-service returns a failure to its caller per `<NEEDS-INPUT: rest-contract-b1-b2>` and does not mark the order paid; (2) H2 zero `order.confirmed`, if observable; (3) the instance keeps serving the next valid request. **Unexpected response shape from Stripe at payment-service** (*blocked, not implementation-ready until `<NEEDS-INPUT: stripe-fault-policy>` is resolved*) - Setup: only if policy permits response-level fault injection at the Stripe boundary. - Trigger: return a response with a missing or renamed payment status field. - Assertions: payment-service returns a failure to order-service; H2 zero `order.confirmed`; payment-service serves the next valid request. If not permitted, the real Stripe response shapes exercised by **Successful checkout publishes order.confirmed**, **Stripe card decline publishes no fulfillment event** and **Stripe processing error publishes no fulfillment event** are the only B3 shape coverage. **Unexpected response shape from order-service at cart-service** (Category B; requires `<NEEDS-INPUT: fault-injection-and-stubbing>`) - Setup: a cart-service instance configured to call a stub of order-service. - Trigger: for each variant (order identifier missing; error body under a success status; non-JSON body), submit checkout. - Assertions: (1) cart-service does not report success to the client; (2) the client receives the failure defined by `<NEEDS-INPUT: rest-contract-b1-b2>`; (3) cart-service serves the next valid request. **Malformed order.confirmed event at fulfillment-service** (*blocked, not implementation-ready until `<NEEDS-INPUT: malformed-event-handling>` is resolved*) - Setup: an isolated topic and fulfillment-service consumer (never the shared staging topic). - Trigger: produce one event with a required field removed, then one valid event. - Assertions: (1) the malformed event is handled by the defined path (`<NEEDS-INPUT: malformed-event-handling>`); (2) H3 poll shows the valid event's fulfillment effect within `SETTLE_TIMEOUT`, proving no halt. ## 6. Failure Mode & Contract Testing All four boundaries (B1–B4) have implied contracts and are covered below. Contract assertions target status codes, required fields and timing guarantees once they are defined, never message text, headers, log output or field ordering. Until `<NEEDS-INPUT: rest-contract-b1-b2>` and `<NEEDS-INPUT: kafka-topic-and-schema>` are resolved, contract tests assert only the invariants marked *Explicit in inputs* or *Inferred from architecture pattern* below, and are incomplete beyond them. **B1: cart-service → order-service** - Unexpected shape: **Unexpected response shape from order-service at cart-service**. Correct degraded behavior: cart-service reports a failure to the client and never reports success without a valid order identifier (*Inferred from architecture pattern*); the specific status and error body are `<NEEDS-INPUT: rest-contract-b1-b2>`. Incomplete until resolved. - Delayed: **order-service slow response beyond cart-service timeout**. Correct degraded behavior: cart-service returns a defined timeout failure; whether an order continues to completion after abandonment is `<NEEDS-INPUT: timeout-and-retry-policy>`. **B2: order-service → payment-service** - Unexpected shape: **Unexpected response shape from payment-service at order-service**. Correct degraded behavior: fail closed, no order marked paid, no `order.confirmed` (*Inferred from architecture pattern*). - Delayed: **payment-service slow response beyond order-service timeout**. Correct degraded behavior: bounded wait, then the policy-defined path (`<NEEDS-INPUT: timeout-and-retry-policy>`), with no charged-but-unfulfilled state left unreconciled. - Unavailable: **payment-service unavailable at order-service boundary**. Correct degraded behavior: failure returned promptly, no Stripe call, no event (*Explicit in inputs* for the no-event invariant). **B3: payment-service → Stripe API** - Real error responses: **Stripe card decline publishes no fulfillment event** and **Stripe processing error publishes no fulfillment event** exercise Stripe's actual contract for failure responses. Correct degraded behavior: failure returned to order-service, no event (*Explicit in inputs*). - Delayed or unreachable: **Stripe unreachable or timing out from payment-service**, blocked by `<NEEDS-INPUT: stripe-fault-policy>`. Correct degraded behavior: failure returned to order-service with no event; payment reconciliation per `<NEEDS-INPUT: timeout-and-retry-policy>`. - Unexpected shape: **Unexpected response shape from Stripe at payment-service**, blocked by `<NEEDS-INPUT: stripe-fault-policy>`. Correct degraded behavior: fail closed (*Inferred from architecture pattern*). **B4: `order.confirmed` on Kafka → fulfillment-service** - Publish-side failure: **Kafka publish failure after successful payment**. Correct degraded behavior: `<NEEDS-INPUT: kafka-publish-failure-behavior>`. The scenario is incomplete until resolved, because "the publish failed" alone is not an expectation. - Schema conformance: **order.confirmed payload consistency** is the primary contract test of the published event against its schema. - Consume-side malformed input: **Malformed order.confirmed event at fulfillment-service**. Correct degraded behavior: defined handling of the bad event and continued processing of later valid events (*Inferred from architecture pattern*); handling path `<NEEDS-INPUT: malformed-event-handling>`. ## 7. Flakiness & Isolation Risk Assessment - **Stripe card decline publishes no fulfillment event**, **Stripe processing error publishes no fulfillment event**, **payment-service unavailable at order-service boundary**, **payment-service slow response beyond order-service timeout**, **order-service slow response beyond cart-service timeout**, **Stripe unreachable or timing out from payment-service**, **Unexpected response shape from payment-service at order-service**, **Unexpected response shape from Stripe at payment-service** and **Unexpected response shape from order-service at cart-service** all rely on absence assertions (no event). Risk: a window that is too short passes falsely, and a dead consumer passes falsely. Mitigation: H1 consumer readiness, H2 window derived from measured latency, the positive control from **Successful checkout publishes order.confirmed** run first in the same suite, and correlation by order identifier. - **Successful checkout publishes order.confirmed**, **order.confirmed payload consistency**, **Charged amount matches cart total**: timing-dependent async assertions. Mitigation: H3 bounded polling with `SETTLE_TIMEOUT`, no fixed sleeps, and an explicit timeout failure message distinguishing "event never arrived" from "event arrived malformed". - Real Stripe test-mode (all Category A scenarios): rate limiting and transient network errors. Mitigation: retry with bounded attempts and backoff only around test-fixture creation and Stripe lookups. The checkout trigger is never retried, since a retry would mask double-charge behavior. - **Duplicate checkout submission**: concurrent submissions are inherently non-deterministic in ordering. Mitigation: repeat the concurrent variant a fixed number of times and assert the invariant on every iteration. The scenario is not implementation-ready until `<NEEDS-INPUT: idempotency-contract>` is resolved. - Shared staging state (all scenarios): parallel suite runs and other teams' traffic pollute topics and data. Mitigation: `RUN_ID` namespacing, unique consumer groups, and serialization of the suite in CI. `<NEEDS-INPUT: ci-integration>` - Fault-injection scenarios (**payment-service unavailable at order-service boundary**, **payment-service slow response beyond order-service timeout**, **order-service slow response beyond cart-service timeout**, **Kafka publish failure after successful payment**): an unremoved fault degrades staging for everyone. Mitigation: always-run teardown, scoping to `RUN_ID` traffic, and a suite-start check that no stale fault rules exist. These scenarios remain blocked until `<NEEDS-INPUT: fault-injection-and-stubbing>` is resolved. - **Malformed order.confirmed event at fulfillment-service**: a poison message on a shared topic can halt other consumers. Mitigation: run only on an isolated topic and consumer. Blocked until `<NEEDS-INPUT: malformed-event-handling>` is resolved. - **Stripe unreachable or timing out from payment-service** and **Unexpected response shape from Stripe at payment-service**: a real third-party dependency even in test-mode. Mitigation: coverage of these two is contract-level only until `<NEEDS-INPUT: stripe-fault-policy>` permits a live-path fault. - **Unexpected response shape from payment-service at order-service** and **Unexpected response shape from order-service at cart-service**: low flakiness because the stub is deterministic. Mitigation: per-test stub lifecycle and an isolated instance. ## 8. Open Questions & Data Requests - `<NEEDS-INPUT: checkout-endpoint-contract>`: What is the exact endpoint, request body and success/failure response contract for submitting a checkout to cart-service? - `<NEEDS-INPUT: rest-contract-b1-b2>`: What are the request and response schemas, status codes, error bodies, currency and rounding rules for B1 (cart-service → order-service) and B2 (order-service → payment-service)? - `<NEEDS-INPUT: payment-method-input>`: How does a Stripe test-mode payment method reach payment-service (token in the checkout request, saved customer, or another path)? - `<NEEDS-INPUT: stripe-confirmation-mode>`: Is payment confirmation at Stripe fully synchronous from payment-service's perspective, or does it depend on webhooks or asynchronous confirmation? Which Stripe API version is pinned? - `<NEEDS-INPUT: order-confirmed-publisher>`: Which service publishes `order.confirmed`: payment-service, order-service, or another? - `<NEEDS-INPUT: kafka-topic-and-schema>`: What are the topic name, message key, payload schema, and delivery guarantees (at-least-once, ordering) for `order.confirmed`? - `<NEEDS-INPUT: kafka-test-access>`: Can a test harness consume from the staging Kafka topic with its own consumer group, and with what credentials? - `<NEEDS-INPUT: fulfillment-observable-effect>`: How can fulfillment-service's processing of an event be observed (API, record, or downstream event)? - `<NEEDS-INPUT: order-status-read-endpoint>`: Does order-service expose an endpoint to read an order's state and total, and does the existing Newman collection already use it? - `<NEEDS-INPUT: failed-payment-order-state>`: After a payment failure, what should the order's state be (cancelled, failed, retryable pending), what is returned to the client, and is cart content preserved or rolled back? - `<NEEDS-INPUT: timeout-and-retry-policy>`: What are the configured timeouts and retry policies for B1, B2 and B3? What must happen when a payment succeeds after the caller has already timed out (reconcile, refund, or confirm late), and does payment-service retry Stripe processing errors? - `<NEEDS-INPUT: kafka-publish-failure-behavior>`: When payment succeeds but publishing `order.confirmed` fails, what is the intended behavior (retry, outbox, refund, pending order)? - `<NEEDS-INPUT: idempotency-contract>`: Does checkout support idempotency keys or duplicate detection, and what should a duplicate submission return and charge? - `<NEEDS-INPUT: malformed-event-handling>`: How should fulfillment-service treat a malformed `order.confirmed` event (skip, dead-letter, halt), and can an isolated topic and consumer be provisioned for the test? - `<NEEDS-INPUT: fault-injection-and-stubbing>`: Can staging support injecting latency, refused connections or broker faults scoped to test traffic, and can a service instance be configured to call a stub of its downstream? - `<NEEDS-INPUT: stripe-fault-policy>`: Does the policy that Stripe calls use the official test-mode API rule out a network-level fault or response stub in front of Stripe for failure-injection and contract-drift tests? - `<NEEDS-INPUT: test-data-seeding-and-teardown>`: How are test carts, products and stock seeded, which identifiers accept a `RUN_ID`, and how are test orders removed afterward? - `<NEEDS-INPUT: ci-integration>`: Where will this suite run in CI, how is it serialized against the shared staging environment, and what is the preferred language and framework for the Kafka-capable harness?