Restore the Perl client runtime and add a packaging smoke test to prevent shipping an unusable SDK

[cferrys]

Summary

The repository currently advertises a usable Perl client, but the runtime module tree has been removed while the build metadata, README, and examples still depend on it. As a result, the project cannot be used as a client library in its current state: Hlquery::Client is referenced everywhere, but lib/Hlquery/Client.pm and the rest of lib/ are no longer present.

Context

The most recent cleanup removed the legacy Perl modules, but the repository still positions itself as a modular Perl API client for hlquery. This creates a hard release blocker:

• README.md instructs users to use Hlquery::Client; and documents a full object model around Hlquery::Client, Hlquery::Collections, Hlquery::Documents, Hlquery::Request, Hlquery::Response, and Hlquery::Search.
• All shipped examples (example.pl, examples/basic_usage.pl, examples/collections.pl, examples/documents.pl, examples/flush.pl, examples/search.pl) import Hlquery::Client.
• Makefile.PL still declares VERSION_FROM => 'lib/Hlquery.pm', but that file no longer exists.
• The tracked tree at HEAD contains no lib/ directory at all, so a direct require Hlquery::Client fails immediately.

For a high-performance search engine, the client SDK is part of the operational path for ingestion, collection management, and query execution. Shipping a repository that cannot be installed or imported blocks adoption entirely and undermines confidence in the surrounding API surface.

Proposed Implementation

1. Restore a minimal supported runtime module set under lib/ that matches the public API still documented in README.md and used by the example scripts.
2. Decide explicitly whether the project is still a CPAN-style library or only an examples/docs repository.
3. If it remains a library:
   • Reintroduce Hlquery.pm and the canonical modules required by the documented API.
   • Align Makefile.PL and cpanfile with the actual runtime dependency graph.
   • Add a smoke test that validates the release shape, at minimum:
     • perl -Ilib -e 'require Hlquery::Client'
     • metadata generation from Makefile.PL
     • one non-network constructor/import test for the client surface
4. If it is no longer intended to ship the client runtime:
   • remove library-installation instructions from README.md
   • move examples behind a clear “requires external hlquery Perl client package” boundary
   • update package metadata so the repo no longer presents itself as installable client code

Impact

Addressing this fixes the highest-severity problem in the repository: the Perl SDK currently cannot be imported or packaged. Restoring a valid runtime and enforcing a smoke test prevents broken releases, keeps client integrations viable, and gives downstream users a stable entry point into hlquery’s search and document APIs.