[woahwhattheheck]

Closes #4

/claim #4

Summary

Completes the previously claimed compliance lifecycle surface against the contract ABI that is actually verified in the current SDK.

• preserves the existing boolean checkWhitelist() API while validating Stellar account addresses with a typed error;
• adds getComplianceStatus() so a confirmed false result is distinct from an unavailable/malformed read;
• adds stable typed lifecycle status/codes and ComplianceLifecycleError;
• adds diagnoseLifecycle() for non-sensitive capability reporting;
• adds updateWhitelist(address, approved) as the issue-allowed explicit admin gate: signer presence is enforced first, then the SDK returns typed ADMIN_UPDATE_UNSUPPORTED because no verified whitelist-write contract method exists in current source;
• documents the read/admin lifecycle, error model, role-aware guardrails, and compliance boundary;
• adds eight focused regression cases for read states, invalid input, admin signer gates, diagnostics, and typed errors.

Why the admin path is gated

Current sponsor source exposes the verified read call is_whitelisted. The repo's admin-receipt model can format whitelist add/remove receipts, but there is no transaction implementation or verified contract whitelist-write method in the SDK. This PR does not fabricate add_whitelist, set_whitelist, or another guessed Soroban entrypoint.

Acceptance traceability

#	Acceptance criterion	Evidence
1	Compliance client module implemented	src/compliance.ts lifecycle surface
2	Whitelist read checks supported	legacy checkWhitelist() + tri-state internal read
3	Admin updates supported or explicitly gated	updateWhitelist() explicit typed gate
4	Admin signer requirement enforced	unsigned mutation -> SIGNER_REQUIRED before unsupported gate
5	Typed invalid/unauthorised errors	ComplianceLifecycleError with INVALID_ADDRESS, SIGNER_REQUIRED, ADMIN_UPDATE_UNSUPPORTED
6	Tests cover read/admin paths	tests/compliance-lifecycle.test.ts (8 focused cases authored)
7	Lifecycle docs	docs/compliance-lifecycle.md + updated API reference

Validation truth

Branch is based on sponsor main@69fff2c7e8c6fe801428fc1bb71d064c5c94949c; final fence confirmed sponsor main remains at that SHA, issue #4 has no PR cross-reference, and the pre-existing @woah issue comment /claim #4 remains the only issue claim.

Connector compare: 7 commits ahead / 0 behind, 7 scoped paths. Static readback confirmed the compatibility read, typed status API, Stellar address validation, signer-first mutation gate, unsupported-write code, lifecycle diagnostic, public exports, all four documented public methods, and 8 focused test cases.

A peer execution request was sent for exactly npm test -- --runInBand tests/compliance-lifecycle.test.ts. No execution result has been received yet in this publication step, so no test/build/CI green result is claimed here and no broad suite was run.

Compensation

I, @woahwhattheheck (GitHub ID 293286387), am continuing the existing original issue #4 contribution and affirmatively request sponsor review, contributor credit, and any eligible GrantFox OSS / Official Campaign FWC26 compensation for this implementation. Please confirm eligibility, accepted scope, payable amount, and settlement route if applicable. The Maybe Rewarded label is conditional; no award or payment is asserted.