feat: person identity matching with detection, confirmation and audit trail

Implements enterprise-grade identity resolution (detect → suggest → confirm)
for Person ↔ User linking. Matches are detected automatically on person
creation and user account creation, then surfaced to organisers for explicit
confirmation or dismissal. No silent auto-linking.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

api/app/Models/Person.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Models;
 
+use App\Enums\IdentityMatchStatus;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
@@ -11,6 +12,7 @@ use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;
 use Illuminate\Database\Eloquent\SoftDeletes;
 
 final class Person extends Model
@@ -74,6 +76,17 @@ final class Person extends Model
         return $this->hasMany(ShiftAssignment::class);
     }
 
+    public function identityMatches(): HasMany
+    {
+        return $this->hasMany(PersonIdentityMatch::class);
+    }
+
+    public function pendingIdentityMatch(): HasOne
+    {
+        return $this->hasOne(PersonIdentityMatch::class)
+            ->where('status', IdentityMatchStatus::PENDING);
+    }
+
     public function scopeApproved(Builder $query): Builder
     {
         return $query->where('status', 'approved');

api/app/Models/PersonIdentityMatch.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use App\Enums\IdentityMatchConfidence;
+use App\Enums\IdentityMatchMethod;
+use App\Enums\IdentityMatchStatus;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+final class PersonIdentityMatch extends Model
+{
+    use HasFactory;
+    use HasUlids;
+
+    public const UPDATED_AT = null;
+
+    protected $fillable = [
+        'person_id',
+        'matched_user_id',
+        'matched_on',
+        'confidence',
+        'status',
+        'resolved_by_user_id',
+        'resolved_at',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'matched_on' => IdentityMatchMethod::class,
+            'confidence' => IdentityMatchConfidence::class,
+            'status' => IdentityMatchStatus::class,
+            'resolved_at' => 'datetime',
+        ];
+    }
+
+    public function person(): BelongsTo
+    {
+        return $this->belongsTo(Person::class);
+    }
+
+    public function matchedUser(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'matched_user_id');
+    }
+
+    public function resolvedBy(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'resolved_by_user_id');
+    }
+
+    public function scopePending(Builder $query): Builder
+    {
+        return $query->where('status', IdentityMatchStatus::PENDING);
+    }
+
+    public function scopeConfirmed(Builder $query): Builder
+    {
+        return $query->where('status', IdentityMatchStatus::CONFIRMED);
+    }
+
+    public function scopeDismissed(Builder $query): Builder
+    {
+        return $query->where('status', IdentityMatchStatus::DISMISSED);
+    }
+}

api/app/Models/User.php

@@ -64,6 +64,11 @@ final class User extends Authenticatable
         return $this->hasMany(UserInvitation::class, 'invited_by_user_id');
     }
 
+    public function identityMatches(): HasMany
+    {
+        return $this->hasMany(PersonIdentityMatch::class, 'matched_user_id');
+    }
+
     public function organisationTags(): HasMany
     {
         return $this->hasMany(UserOrganisationTag::class);