Domain model

1. Counterparty
2. CheckStatus (enum)
3. CheckResult
4. VerificationReport
5. RiskAssessment
6. Evidence
7. VerificationOutcome

Everything is an immutable value object. Identifiers are normalised on construction so the cache key and downstream comparisons are stable.

Counterparty

new Counterparty(
    name: 'Acme Sp. z o.o.',
    country: 'PL',        // ISO-3166-1 alpha-2, upper-cased
    nip: '123-456-78-90', // normalised to digits: 1234567890
    iban: 'PL61 1090 ...',// normalised: no spaces, upper-cased
    euVat: 'pl1234567890',// normalised: PL1234567890
);

• Validates a non-empty name and a 2-letter country.
• fingerprint() returns a stable sha256 over the normalised identifiers (no display name) - used as the AI cache key, so it carries no free-form PII.
• Helpers: hasNip(), hasIban(), hasEuVat().

CheckStatus (enum)

Pass, Fail, Warning, Inconclusive.

• isAdverse() - only Fail.
• isConclusive() - everything except Inconclusive.
• severity() - orders statuses (Pass < Inconclusive < Warning < Fail).

CheckResult

The deterministic outcome of one check - hard facts only.

CheckResult::pass($source, $checkName, $summary, $completedAt, $raw, $proofId);
CheckResult::fail(...);
CheckResult::warning(...);
CheckResult::inconclusive($source, $checkName, $reason, $completedAt, $raw);

• source - a stable id, e.g. pl.white_list, used by risk rules to find results.
• proofId - a due-diligence proof token (e.g. the White List search identifier) kept with the timestamp so the lookup can be evidenced later.
• raw - the provider’s structured payload (adapters must avoid storing unnecessary PII).

VerificationReport

An immutable collection of CheckResult. Useful queries:

$report->results();              // list<CheckResult>
$report->fromSource('pl.krs');   // results from one source
$report->hasAdverseFindings();   // any Fail?
$report->hasInconclusive();      // any Inconclusive?
$report->worstStatus();          // CheckStatus

RiskAssessment

The advisory output of a RiskStrategy.

$assessment->level;                 // RiskLevel: Low | Medium | High | Critical
$assessment->score;                 // float 0.0-1.0
$assessment->summary;               // human-readable
$assessment->requiresHumanReview(); // bool
$assessment->evidence;              // list<Evidence>
$assessment->groundedEvidence();    // only evidence with a source URL

RiskLevel::fromScore() maps a normalised score onto a level.

Evidence

A single grounded claim: claim + optional sourceUrl + confidence (0.0-1.0).

Evidence::grounded('Listed on the EU consolidated list', 'https://...', 0.95);
Evidence::ungrounded('Heard via a forum', 0.2); // no source -> treated as inconclusive

Evidence without a source URL is “ungrounded” and must never be promoted to a confirmed fact - a property the AI strategy relies on.

VerificationOutcome

What Verifier::verify() returns: counterparty, report, assessment, plus requiresHumanReview() and hasAdverseFindings() shortcuts.