feat: add compliance batch query utilities (Closes #50)

[panditdhamdhere]

Description

Adds typed batch compliance queries for admin dashboards that need to check
multiple investor whitelist states without unbounded RPC fan-out or
all-or-nothing failure.

ComplianceModule.checkWhitelistBatch() validates each input before RPC,
preserves input order, limits concurrency, deduplicates repeated addresses, and
represents failures independently. Batch diagnostics contain only aggregate
counts and classified failure codes—never addresses, raw provider errors, URLs,
headers, or credentials.

Design decisions

• Concurrency defaults to 4 and is bounded between 1 and 20.
• Identical valid addresses are queried once by default.
• Invalid, muxed, and contract addresses are handled per item.
• Failed items use safe NetworkFailureDiagnostic data.
• Unsuccessful simulations are treated as failures, not as confirmed
  non-whitelisted results.
• No automatic retry is performed because hidden retries can amplify provider
  load during rate limiting.
• Invalid arbitrary input is not echoed in results; callers correlate through
  item.index.

Files added

• src/compliance/batch.ts
• src/types/compliance-batch.ts
• src/errors/compliance.ts
• src/diagnostics/compliance.ts
• tests/compliance-batch.test.ts
• docs/compliance-batch-queries.md

Files updated

• src/compliance.ts
• src/client-factory.ts
• src/index.ts
• src/testing/mock-client.ts
• tests/mock-client.test.ts
• README.md
• CONTRIBUTING.md
• docs/api-reference.md
• docs/testing.md
• docs/test-first-contribution-guide.md
• docs/acceptance-criteria-traceability.md

Closes: #50

---

Evidence Checklist

1. Issue Reference

• This PR references a tracked issue (Closes #50).
• The linked issue's acceptance criteria are copied into Section 6 below.

2. Implementation Summary

• A clear description of what changed is provided above.
• A brief explanation of why this approach was chosen is included.
• All files added, modified, or removed are listed or summarised.

3. Tests

• New or updated unit tests cover every added or changed public method.
• Tests use the mock client where appropriate.
• Production behavior is tested with deterministic mocks rather than live RPC.

Tests cover:

• mixed valid, malformed, muxed, and contract addresses;
• input-order preservation;
• partial and complete query failures;
• unsuccessful simulation handling;
• safe malformed-response diagnostics;
• deduplication and optional deduplication disabling;
• bounded concurrency;
• empty and oversized batches;
• rate limiting and retryAfterSeconds;
• address-free diagnostic roll-ups;
• mock-client batch parity.

4. Commands Run

npm run check
git diff --check

Command output

> @aegis/sdk@0.1.0 check
> npm run build && npm test -- --runInBand && npm run test:compat

> @aegis/sdk@0.1.0 build
> tsc

> @aegis/sdk@0.1.0 test
> jest --runInBand

PASS tests/compliance-batch.test.ts
PASS tests/client-factory.test.ts
PASS tests/events-decoder.test.ts
PASS tests/investor.test.ts
PASS tests/role.test.ts
PASS tests/events-module.test.ts
PASS tests/admin-receipts.test.ts
PASS tests/config.test.ts
PASS tests/network-failures.test.ts
PASS tests/client.test.ts
PASS tests/mock-client-examples.test.ts
PASS tests/mock-client.test.ts

Test Suites: 12 passed, 12 total
Tests:       131 passed, 131 total
Snapshots:   0 total
Time:        2.599 s
Ran all test suites.

> @aegis/sdk@0.1.0 test:compat
> node scripts/check-compat.mjs

Browser compatibility: bundle resolved without Node-only imports.
Node compatibility: public SDK entrypoint and signer initialized.

5. CI Status

• All GitHub Actions checks pass on this PR.
• If a CI step failed, a root-cause explanation will be provided below.

6. Acceptance Criteria Coverage — Traceability Table

#	Acceptance Criterion	SDK Module(s)	Test(s)	Doc(s)	Behaviour Verification
1	Batch compliance query is implemented.	src/compliance.ts, src/compliance/batch.ts, src/types/compliance-batch.ts	tests/compliance-batch.test.ts, tests/mock-client.test.ts	docs/compliance-batch-queries.md, docs/api-reference.md	checkWhitelistBatch() returns one typed item per input and a batch summary.
2	Invalid addresses are handled per item.	src/compliance/batch.ts	Mixed-input and invalid-input tests	docs/compliance-batch-queries.md	StrKey validation occurs before RPC; malformed, muxed, and contract addresses receive distinct item codes.
3	Partial failures are represented safely.	src/compliance/batch.ts, src/diagnostics/compliance.ts	Partial failure, exhaustion, malformed response, and rate-limit tests	docs/compliance-batch-queries.md	Successful rows remain resolved; failures receive fixed messages and safe diagnostics without rejecting the batch.
4	Tests cover mixed valid and invalid input.	tests/compliance-batch.test.ts	returns typed results in input order for mixed valid and invalid input	docs/test-first-contribution-guide.md	Six mixed inputs preserve order while only two valid addresses reach the query function.
5	Docs explain performance and rate-limit assumptions.	src/compliance/batch.ts	Concurrency, deduplication, and rate-limit tests	docs/compliance-batch-queries.md, README.md	Documentation states N unique addresses require N simulations, concurrency defaults to 4, and no automatic retry occurs.
6	Diagnostics avoid sensitive data.	src/diagnostics/compliance.ts, src/compliance/batch.ts	Secret-redaction and address-free diagnostic tests	docs/compliance-batch-queries.md	Roll-ups contain counts and classified codes only; tests assert addresses, invalid input, URLs, and tokens are absent.

---

Reviewer Notes

Existing single-query behavior

The batch path uses a stricter internal query than checkWhitelist() so an
unsuccessful simulation or non-boolean response becomes a per-item failure
instead of being displayed as “not whitelisted.”

The existing public checkWhitelist() behavior remains fail-closed and returns
false for unsuccessful or non-boolean responses.

Retry behavior

The batch utility deliberately does not retry automatically. Applications
should retain successful rows, honor retryAfterSeconds, and retry only failed
rows after backoff.

Diagnostics privacy

Valid addresses remain available on per-item application results because admin
tables need them. Invalid arbitrary input is omitted. The batch-level diagnostic
is address-free and intended for logs, telemetry, and support reports.

Existing tooling limitation

npm run lint and npm run format cannot currently run on this branch or
main because the scripts invoke eslint and prettier, but those packages are
not listed in devDependencies. CI runs npm run check, which passes.