Harden and Test the New `SAM` Client Surface Before It Becomes a Compatibility Trap

[cferrys]

Summary

The newly added SAM API surface is already exported, documented, and marked as supported, but it does not yet have the validation and test rigor used by the rest of the client. This creates a high-risk gap where invalid inputs can silently leak into requests and future server/client drift will not be caught early.

Context

Recent work has been heavily focused on documentation, and the current uncommitted changes expand that by adding SAM usage to README.md, exposing SAM from index.js, wiring it into lib/Client.js, and declaring /sam/search, /sam/status, and /sam/history as supported in lib/conformance.js.

The problem is that lib/SAM.js is materially less defensive than adjacent APIs:

• It throws generic Error instances instead of the client’s ValidationException pattern used in utils/Validator.js.
• history() coerces limit with Number(limit) and forwards the result without validating that it is finite and positive, so values like 'abc', NaN, or 0 can become malformed query parameters.
• There is no visible offline or package-level test coverage for SAM; test/offline-smoke.js does not exercise it, and the package scripts only expose general conformance/offline smoke entry points.

For a high-performance search/database wrapper, the client contract matters as much as raw throughput: weak validation and missing endpoint tests cause production failures to show up late, at request time, against live servers.

Proposed Implementation

1. Add dedicated validator helpers for SAM input rules, or extend Validator with shared primitives so SAM uses the same exception model as the rest of the client.
2. Validate history(limit) explicitly as a positive finite integer before issuing the request.
3. Add focused offline tests for:
   • client.sam() availability
   • correct route/method/query construction for search, status, and history
   • rejection of invalid collection names, empty queries, invalid params objects, and invalid history limits
4. Add a conformance-oriented test case that fails if SAM routes are marked as supported in the manifest but the client behavior is not actually exercised.
5. Keep the README examples only after the behavior is covered by tests, so documentation does not get ahead of the supported contract.

Impact

This closes the highest-risk gap in the current change set: the client will stop advertising undocumented runtime behavior as stable. It will improve SDK reliability, prevent malformed requests from reaching hlquery servers, and reduce the chance that SAM becomes a long-term compatibility problem as the search engine evolves.