Enforce the published OpenAPI contract with property-based CI

[yhay81]

Problem

The OpenAPI document is linted statically, but no independent black-box gate verifies it against the running server. A deterministic Schemathesis v4.24.3 discovery run selected all 46 operations and generated 403 cases. It found 19 unique contract failures:

• 18 responses used valid runtime error statuses such as 404 or 422 that the operation did not document;
• DELETE /suppressions/{email} returned { object, email, deleted } while the shared deletion schema required { object, id, deleted };
• eight operations repeatedly rejected inputs that the OpenAPI schema described as valid because runtime string constraints were stricter.

No generated case caused a 5xx response, but generated clients and direct HTTP users cannot currently rely on the published error and validation contract.

Scope

Align the checked-in OpenAPI document with the existing runtime contract and add a deterministic, loopback-only property-based CI job. This is contract hardening, not a runtime behavior change.

Acceptance criteria

• Every protected operation documents the shared JSON error shape for non-success responses without masking server errors.
• Suppression deletion documents the actual email-keyed response.
• OpenAPI request constraints match the corresponding Zod constraints for the cases identified by the discovery run.
• Pin the official Schemathesis v4.24.3 container by OCI digest rather than a floating tag.
• Refuse any non-loopback contract-test target before starting the test tool.
• Exercise all 46 operations against local in-memory HayaSend with deterministic generation.
• Require not_a_server_error, status-code, content-type, and response-schema conformance.
• Do not persist generated request or response bodies as artifacts.
• Keep Node, Python, and Go official SDK gates green.
• Document the new direct HTTP compatibility evidence and tool/version pin.

Non-goals

This issue does not replace scenario-based SDK tests, connect to AWS or SES, or require generated tests to create every stateful resource graph.

[yhay81]

Merged and verified on protected main.

Evidence:

• PR: Enforce the OpenAPI runtime contract #57
• exact merged commit: 1b5d285d22f5d1f3221e29a511b67487d8583a5d (GitHub signature verification: valid)
• exact-main CI: https://github.com/haya-inc/hayasend/actions/runs/30214715320
  • test: passed (29 files / 282 tests, conformance, build, CloudFormation, OpenAPI, Lambda bundles, container smoke)
  • python-sdk: passed
  • openapi-contract: passed for all 46 operations
• exact-main CodeQL: https://github.com/haya-inc/hayasend/actions/runs/30214715048
  • Actions: passed
  • JavaScript/TypeScript: passed
  • Python: passed
  • open repository code-scanning alerts after the run: 0
• local property evidence before merge:
  • positive + negative: 46/46 operations, 436/436 generated cases
  • positive-only confirmation: 46/46 operations, 871/871 generated cases
• official Schemathesis 4.24.3 OCI index digest independently verified as sha256:dd1ebf7519958c34c276a65c20f9f2f808dbefb06c86163eb284ff5674c6a9f3
• runtime baseline: Node 24.18.0, npm 12.0.1; direct dependency audit reported no available updates and 0 vulnerabilities

Safety remained fail-closed: loopback-only target validation, generated webhooks rewritten to the non-delivering 127.0.0.1:9 sink, read-only/capability-free test container, and no request/response report artifacts.

The earlier Go-SDK acceptance line is intentionally superseded by accepted direction #81 and execution plan #84: PR #55 remains parked and was not imported into this production-semantics contract gate. Existing Node and Python SDK gates remained green.