BryanTheLai / BryanTheLai/fraud-v2
Gateway signal contract and mock vendor matrix
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Rank
P0. Feasible locally. Production blocked.
## Goal
Create one canonical gateway signal contract for KYC/KYB/liveness/device/consortium-shaped signals. Do not call real vendors.
## Why
Gateway signals feed features, decisions, graph evidence, compliance evidence, and cockpit UI. Without canonical events, later work will couple to mock vendor internals.
## Current Assets
- `src/fraud_v2/domain/events.py`
- `src/fraud_v2/domain/enums.py`
- `src/fraud_v2/connectors/mock_vendors.py`
- `src/fraud_v2/connectors/signal_lab.py`
- `src/fraud_v2/converters/raw_events.py`
## Build
- Add `GatewaySignalType`: `KYC`, `KYB`, `LIVENESS`, `DEVICE_INTEL`, `CAMERA_METADATA`, `CONSORTIUM`, `SANCTIONS_SHAPE`.
- Add `GatewaySignalStatus`: `OK`, `REVIEW`, `DENY_SHAPE`, `STALE`, `TIMEOUT`, `ERROR`, `UNKNOWN`.
- Add `GatewaySignalObserved` payload.
- Add `ConsortiumRiskObserved` payload.
- Extend `CanonicalPayload`.
- Build `GatewaySignalConverter` from `ConnectorResult` to `EventEnvelope`.
- Simulate timeout, stale, denied-shape, review, unknown, malformed.
## Missing
- Typed gateway payloads.
- Single connector-to-event converter.
- Tests proving features/decisions do not import vendor classes.
## Acceptance
- Canonical gateway and consortium events exist.
- Existing mock KYC/device/consortium/camera/KYB outputs map to canonical events.
- Converter tests cover valid, missing field, bad enum, duplicate idempotency key, stale, timeout, unsafe PII-like input.
- Docs say real vendors are blocked by contracts, legal review, credentials, and permitted use.
## Out Of Scope
- Real vendor calls.
- Real PII.
## Truth Boundary
- No real PII.
- No real KYC/KYB/liveness/sanctions/consortium calls.
- No real money movement.
- No real customer messages.
- No real SAR or adverse-action filing.
- If blocked, simulate locally and label it as simulated.
## Links
- Target article: https://www.bryanslab.com/blogs/fraud-2/
- Master spec: https://github.com/BryanTheLai/fraud-v2/blob/feature/full-profile-adapters/docs/target-goal-gap-and-issue-spec.md
- Ranked issue map: https://github.com/BryanTheLai/fraud-v2/blob/feature/full-profile-adapters/docs/issue-evaluation-ranking.md
- Production readiness: https://github.com/BryanTheLai/fraud-v2/blob/feature/full-profile-adapters/docs/production-readiness.md
- Agent rules: https://github.com/BryanTheLai/fraud-v2/blob/feature/full-profile-adapters/AGENTS.md
## Required Proof
- `uv run ruff format --check .`
- `uv run ruff check .`
- `uv run mypy src`
- `uv run pytest -q`
If Docker/full profile changes:
- `docker compose -f infra\docker-compose.yml --profile full config --quiet`
- `docker build -t fraud-v2:local .`
Contributor guide
No contributing guide indexed for this repository
Research direction
Read src/fraud_v2/domain/events.py, src/fraud_v2/domain/enums.py, src/fraud_v2/connectors/mock_vendors.py, src/fraud_v2/connectors/signal_lab.py, and src/fraud_v2/converters/raw_events.py to map the existing event and connector shapes. Run the required pytest, ruff, and mypy commands while working; done means canonical gateway and consortium events, converter coverage for the listed cases, vendor-independent tests, and documentation of the production boundary.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend, documentation, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100