feat(compliance): add explicit status cache strategy

[emirykl]

Description

Adds an explicit, consumer-managed compliance status cache strategy for dashboard reads. The SDK remains cache-free by default; consumers get a narrowly scoped freshness helper and adapter types, while the guide documents TTL, invalidation, stale-data, failure, privacy, and authorization boundaries.

Closes: #63

---

Evidence Checklist

1. Issue Reference

• This PR references tracked issue Add SDK compliance status cache strategy #63.
• Every acceptance criterion is copied into Section 6.

2. Implementation Summary

• Added docs/compliance-status-cache.md with dashboard guidance and risk boundaries.
• Added explicit scope, entry, and adapter types in src/types/compliance-cache.ts.
• Added and exported isComplianceCacheEntryFresh() for exact-scope and expiry validation.
• Added focused boundary and scope tests.
• Linked the strategy from the README and API reference.

The cache stays application-owned so status is never cached invisibly by the SDK. Scope includes network passphrase, contract ID, and address to prevent cross-network, cross-deployment, or cross-account reuse.

3. Tests

• New unit tests cover the added public helper.
• Tests cover the expiry boundary, scope mismatches, malformed persisted scope, future timestamps, and non-finite timestamps.
• The mock client is not applicable because the helper is pure and performs no RPC call.

4. Commands Run

$ npm run build
> tsc
PASS

$ npm test -- --runInBand --no-watchman
Test Suites: 12 passed, 12 total
Tests:       127 passed, 127 total

$ npm run test:compat
Browser compatibility: bundle resolved without Node-only imports.
Node compatibility: public SDK entrypoint and signer initialized.

$ git diff upstream/main...HEAD --check
PASS

npm run check completed its build step, then the default Jest invocation tried to access a sandbox-restricted Watchman socket. The same complete test suite passed with the repository worker's macOS-safe --no-watchman flag. npm run lint cannot start because eslint is not present in this repository's declared/installable dependencies (sh: eslint: command not found); no dependency changes were added outside this issue's scope.

5. CI Status

• All GitHub Actions checks pass on this PR. Pending the first CI run.

6. Acceptance Criteria Coverage — Traceability Table

#	Acceptance Criterion	SDK Module(s)	Test(s)	Doc(s)	Behaviour Verification
1	Cache strategy is documented.	src/types/compliance-cache.ts	tests/compliance-cache.test.ts	docs/compliance-status-cache.md	Defines the opt-in SDK boundary, identity, TTL, storage, failure, and dashboard rules.
2	Stale compliance risk is discussed.	src/compliance.ts	Expiry-boundary and invalid-timestamp cases	docs/compliance-status-cache.md	Documents stale true and stale false, forbids stale authorization, and returns false at expiry.
3	Invalidation assumptions are defined.	ComplianceCacheScope, ComplianceStatusCacheAdapter	Network, contract, and address mismatch cases	Invalidation assumptions section	Defines mutation/event/config/manual/gap invalidation and keeps TTL as the correctness backstop.
4	Optional helper types are added if practical.	ComplianceCacheScope, ComplianceStatusCacheEntry, ComplianceStatusCacheAdapter, isComplianceCacheEntryFresh()	tests/compliance-cache.test.ts	API reference	Public exports compile and the helper rejects unsafe reuse.
5	Dashboard usage guidance is included.	Consumer-managed adapter boundary	Pure helper tests	Dashboard checklist and TypeScript example	Covers UI states, refresh, deduplication, TTL selection, writes, invalidation, and logging.
6	README links to the strategy.	N/A	Documentation link reviewed in diff	README.md	The compliance section links directly to the new guide.

---

Reviewer Notes

Please pay particular attention to the deliberately conservative boundary: cached values are display snapshots only, never transaction authorization decisions, and the SDK does not cache automatically.