Skip to content

REST contract manifest and live completeness gate

Summary

Create a machine-readable REST contract manifest and use it as the canonical test input for the live REST completeness lane.

Beta 0.7.3 Classification

Release Gate. The checked-in OpenAPI contract must become executable enough that native route tests and live REST smoke cannot drift from the documented public /api/v1 surface.

The current Python route tuple is useful, but it is not a durable public contract artifact and can drift from docs/rest/REST-API-CONTRACT.md.

Execution Plan

Historical release context: Beta 0.7.3 REST and Arr execution plan.

Acceptance Criteria

  • [x] a checked-in contract manifest lists every public /api/v1 route, method, safety classification, and expected response envelope
  • [x] route seam tests and live REST smoke consume or validate against the same manifest
  • [x] docs/rest/REST-API-CONTRACT.md is checked against the manifest for route drift
  • [x] adding a new REST endpoint requires updating the manifest and tests
  • [x] POST /api/v1/app/shutdown remains explicitly excluded from live completeness mutation loops

Progress

  • 2026-05-02: Added the first checked-in machine-readable target contract at docs/rest/REST-API-OPENAPI.yaml and a legacy runtime-action parity inventory at docs/rest/REST-API-PARITY-INVENTORY.md. The CI item remains open because route seam tests and live REST smoke do not yet consume the contract.
  • 2026-05-02: Expanded native route seam coverage and live REST smoke route coverage for server/Kad operations, transfer details, shared-file metadata, and search result download/delete-all routes. The CI item remains open until the smoke runner consumes the checked-in OpenAPI contract directly.
  • 2026-05-06: Passed for Release 1. Native route specs and live REST smoke now validate against docs\rest\REST-API-OPENAPI.yaml; the REST contract documentation defers route-table authority to OpenAPI; the unsafe shutdown route is explicitly excluded from live mutation loops.

Completion Evidence

  • Test commits: 3bc65d6, 3101391, b53627d, b8233b0, d907fc2, 69eba5b.
  • Tooling commits: 89810c5, 8b548b3, cffd810, e3b5d24, 9560435, fee7111, f2cc198.
  • Commands: python -m emule_workspace validate; python -m pytest tests\python\test_rest_api_smoke.py -q; python -m emule_workspace build tests --config Release --platform x64; python -m emule_workspace test live-e2e --config Release --platform x64 --suite rest-api.
  • Artifacts: workspaces\v0.72a\state\build-logs\20260506-181540; repos\emulebb-build-tests\reports\rest-api-smoke\20260506-181933-eMule-main-release; repos\emulebb-build-tests\reports\live-e2e-suite\20260506-181933-eMule-main-release\result.json.
  • Live REST contract coverage recorded 81 routes with /app/shutdown skipped as unsafe and completed 8026 stress requests with 0 failures.
  • Beta 0.7.3 revalidation: CI-025 passed the REST contract Python suite (63 tests) and live REST contract smoke: repos\emulebb-build-tests\reports\rest-api-smoke\20260509-144340-eMule-main-release\result.json. The live report recorded 82 OpenAPI routes, 82 registry routes, 81 exercised safe routes, 0 failed routes, and /api/v1/app/shutdown as the single skipped unsafe route.

Pending Revalidation Focus

This gate is passed, but before Release 1 tagging the route-drift evidence should be refreshed with:

  • [x] every OpenAPI route checked against the native route table for method, path, required body, query, path-id, and envelope drift
  • [x] representative success paths for read, safe mutation, destructive confirmation, and async operation routes
  • [x] explicit exclusion of /api/v1/app/shutdown from broad live mutation loops
  • [x] confirmation that aMuTorrent and Arr adapters consume or translate to the native contract instead of changing the native contract

Relationship To Other Items

  • backs CI-011
  • gates FEAT-045 through FEAT-049