Skip to content

Add a short guide for testing idempotency and conflict handling #70

@MuttleyD

Description

@MuttleyD

Context

MIDAS supports idempotent runtime evaluation using request_source and request_id. This is an important part of the runtime contract because callers need to know what happens when they retry the same decision request.

The control-plane example walkthrough already validates idempotent replay and changed-payload conflict behaviour, but this behaviour should be easier for new users to understand.

Scope

Add a concise idempotency and conflict testing section to docs/examples/control-plane.md.

The section should explain:

  • request_source and request_id form the scoped idempotency key;
  • replaying the same request with the same payload should return the same decision/envelope;
  • reusing the same request_source and request_id with a changed payload should return 409 Conflict;
  • this protects callers from accidental duplicate decision records while still detecting conflicting retries.

Include example commands showing:

  • first /v1/evaluate request;
  • exact replay of the same request;
  • changed-payload request using the same request_source and request_id;
  • expected 409 response.

Acceptance Criteria

  • docs/examples/control-plane.md explains idempotent replay in plain language.
  • The section includes copyable example commands.
  • The examples use one of the existing control-plane bundles and validated request IDs.
  • The expected replay and conflict behaviours match the current runtime.
  • The section links to docs/core/runtime-evaluation.md for deeper details.
  • No runtime behaviour is changed.
  • No real secrets are added.
  • git diff --check passes.

Out of Scope

  • Changing idempotency semantics.
  • Changing runtime evaluation behaviour.
  • Adding new endpoints.
  • Adding automation or scripts.
  • Changing the example bundles.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions