feat(#279): cross-language contract test — backend client ↔ AI service Pydantic schemas

[samsolo247]

Summary

Closes #279

Adds the contract test layer described in issue #279 (backlog item #71) to catch JSON schema drift between the NestJS backend client and the FastAPI AI service Pydantic schemas before it reaches production.

Changes

app/backend/scripts/openapi-validate.ts (new)

Shared utility and standalone CLI that:

• Fetches the AI service OpenAPI JSON document over HTTP/HTTPS
• Resolves $ref pointers within the document
• Extracts response schemas by path + method + status code
• Structurally validates a plain object against a schema (required fields, types, enum membership)

Run standalone to check spec drift without tests:

AI_SERVICE_URL=http://localhost:8000 ts-node --transpile-only scripts/openapi-validate.ts

app/backend/test/contract/ai-service.contract.spec.ts (new)

Contract test suite with five assertion groups:

Group	What it checks
Document structure	openapi version string, info, components.schemas
Required v1 paths	All 6 endpoints the backend depends on exist with correct HTTP method + 200 response
Enum correctness	provider_preference values (auto/test/openai/groq); TaskStatus lifecycle values
Required fields	Every response schema's required[] array matches the TypeScript interfaces the backend compiles against
Fixture validation	Real app/ai-service/fixtures/*.json payloads are validated against the declared schemas
Cross-field consistency	Optional vs required fields (e.g. verification/error on humanitarian response)

Live vs CI mode — when AI_SERVICE_URL is set the spec is fetched live; otherwise the test falls back silently to an embedded snapshot so CI runs without a live AI service.

Compile-time type guards — TypeScript asserts functions for all five response interfaces cause a build failure if the backend's internal types drift from the schema shapes.

How to run

cd app/backend
# unit test runner (uses embedded snapshot, no AI service needed)
npm test -- --testPathPattern="test/contract/ai-service.contract.spec"

# with a live AI service
AI_SERVICE_URL=http://localhost:8000 npm test -- --testPathPattern="test/contract/ai-service.contract.spec"

Files affected

• app/backend/scripts/openapi-validate.ts — new
• app/backend/test/contract/ai-service.contract.spec.ts — new

[kilodesodiq-arch]

Hi 👋 Appreciate this PR! The CI is flagging a failing check — could you take a peek at the failed job and push a fix? Happy to help if you need a hand 🙏

[samsolo247]

Hi 👋 Appreciate this PR! The CI is flagging a failing check — could you take a peek at the failed job and push a fix? Happy to help if you need a hand 🙏

Done.
Kindly review again.

[kilodesodiq-arch]

LGTM