feat(proofs): add payroll proof verifier adapter interface

[Dreal-pyper]

Summary

Adds a pluggable payroll proof verifier adapter interface to the SDK so local, testnet, hosted, or future ZK verifier implementations can share the same client contract — the SDK no longer hard-codes a single proof verification path.

What changed

New: packages/core/src/proofs/types.ts

• ProofVerificationStatus — five stable, typed verification states: valid, invalid, expired, unavailable, malformed.
• ProofVerificationInput — canonical input shape (reuses the SDK's ProofPayload plus optional publicInputs, verificationKeyId, expiresAt, context).
• ProofVerificationResult — normalized verdict (status, isValid, sanitized message, verifiedAt, details).

New: packages/core/src/proofs/verifierAdapter.ts

• ProofVerifierAdapter — the pluggable interface (async verify(input)).
• MockProofVerifierAdapter — default network-free mock for tests and local development that simulates all five states (structural validation → malformed, expiresAt in the past → expired, configurable defaultStatus for invalid/unavailable, failWith to simulate thrown adapter errors).
• normalizeProofVerificationError — normalizes any adapter error into an SDK-safe ZkPayrollError (maps unreachable/timeout-style errors to PROOF_VERIFIER_UNAVAILABLE, preserves cause and context).
• proofVerificationMessage / isStructurallyValidProof helpers.

packages/core/src/proofs/errors.ts

• ProofVerificationError (extends ZkPayrollError) with stable codes: PROOF_VERIFICATION_FAILED, PROOF_VERIFIER_UNAVAILABLE, PROOF_VERIFICATION_MALFORMED.

packages/core/src/client.ts — adapter injection

• ProofVerificationClient — SDK consumers inject any adapter via the constructor (defaults to the mock), so verification works out of the box.
• verifyProofWithAdapter — standalone helper for callers that already hold an adapter.
• Both normalize thrown adapter errors automatically.
• Naming note: the class is ProofVerificationClient to avoid colliding with the existing on-chain contract wrapper ProofVerifierClient (./clients), which remains unchanged and importable.

packages/core/src/core/error-codes.ts + packages/core/src/errors.ts + packages/core/src/index.ts

• New error codes registered in ERROR_CODE_REGISTRY (category proof) and exported from the package root.

Tests: packages/core/tests/proof-verifier-adapter.test.ts (31 tests)

• All five states via the mock (no network), structural validation, expiry handling, error normalization (plain Error, strings, objects, ZkPayrollError passthrough, unavailable mapping), client injection, and export-surface non-collision with the contract ProofVerifierClient.

Docs

• New docs/PROOF_VERIFIER_ADAPTER.md — states, client usage, error handling, and a worked example of plugging in a real (hosted) verifier plus an author checklist.
• Regenerated docs/ERROR_CODES.md to include the three new codes (also picks up two eligibility codes that were already registered but missing from the generated file).

Acceptance criteria

• ✅ SDK consumers can inject a proof verifier adapter — new ProofVerificationClient(adapter) / verifyProofWithAdapter(adapter, input).
• ✅ Verification results use stable typed states — closed ProofVerificationStatus union.
• ✅ Mock adapter works in tests without network calls — in-memory only, used as the client default.
• ✅ Docs explain adapter responsibilities and expected error handling — docs/PROOF_VERIFIER_ADAPTER.md.

Verification

• npx jest tests/proof-verifier-adapter.test.ts — 31/31 passing.
• Full node suite: 115 suites pass / 2320 tests pass; the 5 failing suites (amount-normalization, archived-smoke, draft-builder, proof-request-snapshots, receipt-verification) fail identically on dev due to pre-existing type errors unrelated to this change.
• eslint clean on all touched files (one pre-existing no-console warning in src/errors.ts).
• tsc --noEmit introduces zero new errors (61 pre-existing errors on dev untouched).

Note: the issue's suggested paths (src/proofs/verifierAdapter.ts, src/client.ts, test/...) map to the monorepo's actual source at packages/core/...; the legacy root src/ mirror is stale and is not maintained by recent PRs, so this change follows the current packages/core convention.

Close #357

[drips-wave]

@Dreal-pyper Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[github-actions]

@Dreal-pyper this PR currently has merge conflicts.

Please resolve the conflicts before it can be merged automatically.