fix: harden runtime lifecycle and request failure handling

[afoote-mitre]

Stack

2 of 6 in the 0.4.0 review stack.

• Base: af/0.4.0-review-01-dependencies
• Previous: #122
• Next: #124

Why These Changes Are Needed

Search requests also need deterministic process lifecycle behavior and explicit failures at HTTP and dependency boundaries. This range makes startup, readiness, shutdown, malformed candidate handling, and oversized-body handling observable and fail closed, while removing stale maintenance paths that complicated those flows.

Review Size

Changed lines are additions plus deletions in this PR's adjacent diff. Generated files are package-lock.json and api-docs/openapi.json; tests are *.test.js and files under test/.

Category	Changed Lines
Total	1,656
Generated files	72
Tests	949
Non-generated, non-test	635

Change-to-File Map

Change	Why It Is Needed	Primary Implementation Files	Test / Contract Coverage
Add graceful process shutdown	Stop accepting requests, close the HTTP listener, and release reusable OpenSearch clients deterministically.	server.js, utils/runtimeLifecycle.js, utils/searchProvider.js	server.test.js, utils/runtimeLifecycle.test.js, utils/searchProvider.test.js
Make readiness shutdown-aware	Prevent orchestration from routing new traffic to a process after shutdown has started, including while dependency checks are pending.	server.js, routes/index.js, utils/runtimeLifecycle.js	server.test.js, routes/index.test.js, routes/search.integration.test.js
Fail closed on malformed candidates	Avoid silently skipping invalid candidate records and returning an apparently complete semantic-search result.	controllers/searchController.js, utils/searchProvider.js, utils/errors.js	controllers/searchController.test.js, utils/searchProvider.test.js, utils/errors.test.js
Handle oversized JSON explicitly	Return a stable 413 response instead of allowing parser-specific or generic server errors.	server.js, controllers/middleware.js, routes/index.js, utils/constants.js, utils/errors.js	server.test.js, controllers/middleware.test.js, routes/index.test.js, routes/search.integration.test.js
Remove stale maintenance paths	Reduce unreachable/obsolete controller and performance branches that complicated lifecycle and failure handling.	controllers/searchController.js, utils/searchPerformance.js, jest.config.js	controllers/searchController.test.js, utils/searchPerformance.test.js
Validate the packaged runtime	Ensure CI builds and starts the production image and verifies its health and generated API artifact.	.github/workflows/quality.yml, package.json, test/contract/opensearch.js	GitHub Runtime Container job, config/runtime-config.test.js, api-docs/openapi.test.js
Align operational documentation	Document shutdown, readiness, request-size, and malformed-candidate behavior.	README.md, api-docs/openapi.json	api-docs/openapi.test.js

Reviewer Focus

• Trace startup and shutdown ownership across the HTTP server and OpenSearch clients.
• Confirm readiness cannot return success after shutdown begins.
• Review malformed-candidate handling and verify no partial success path remains.
• Confirm the container check validates the packaged runtime rather than only source execution.