docs(trustline): design trustline validation support for issued asset payment flows (Closes #167)

[TheDEV111]

Description

Closes #167

Designs and documents pre-flight trustline validation support for issued asset payment flows on the Stellar network.

Issued asset payments (e.g. USDC, EURT, or custom project tokens) fail on-chain if the recipient account does not have an active, authorized trustline with sufficient capacity. This feature introduces a two-tiered validation model (local pre-flight format validation + network Horizon account inspection) to detect missing or invalid trustlines before building and submitting transactions.

Changes Included

1. Types (src/types/index.ts)

• Restored type exports lost in recent refactor.
• StellarAssetSpec: Represents native XLM or issued asset (code, issuer).
• TrustlineStatus: Status discriminant (valid, native_xlm, missing_trustline, not_authorized, limit_exceeded, account_not_found).
• TrustlineCheckResult: Detailed validation outcome containing capacity, authorization status, and recovery messages.
• TrustlineCheckOptions: Options for amount checking and SDK config overrides.

2. Implementation (src/payments/trustline.ts & src/payments/index.ts)

• validateAssetSpec(asset): Pure local validation for asset code format (1-12 alphanumeric chars) and issuer key format.
• checkDestinationTrustline(destination, asset, options?): Network check looking up recipient balances on Horizon for existence, trustline match, issuer authorization, and capacity (limit - balance >= amount).
• safeCheckDestinationTrustline(...): Non-throwing wrapper returning PocketPayResult<TrustlineCheckResult>.
• verifyPaymentTrustlineOrThrow(...): Pre-flight helper throwing structured PocketPayError on invalid trustlines.

3. Documentation

• docs/adr/0003-trustline-validation.md: Architecture Decision Record detailing decision rationale and consequences.
• docs/trustline-validation.md: User & developer guide with flowcharts, taxonomy, recovery hints, and failure scenario code examples.
• Updated README.md & docs/adr/README.md.

4. Tests (tests/trustline.test.ts)

• 17 unit tests covering all acceptance criteria, local format checks, network simulations, error statuses, and safe/throwing wrappers.

Verification

• Run npm run verify (tsc --noEmit, circular dependency check, vitest suite, build). All 534 unit tests pass cleanly.