Add core mapping system

src/Contracts/RecordMapper.php

···
+<?php
+
+namespace SocialDept\AtpParity\Contracts;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Contract for bidirectional mapping between Record DTOs and Eloquent models.
+ *
+ * @template TRecord of Data
+ * @template TModel of Model
+ */
+interface RecordMapper
+{
+    /**
+     * Get the Record class this mapper handles.
+     *
+     * @return class-string<TRecord>
+     */
+    public function recordClass(): string;
+
+    /**
+     * Get the Model class this mapper handles.
+     *
+     * @return class-string<TModel>
+     */
+    public function modelClass(): string;
+
+    /**
+     * Get the lexicon NSID this mapper handles.
+     */
+    public function lexicon(): string;
+
+    /**
+     * Convert a Record DTO to an Eloquent Model.
+     *
+     * @param  TRecord  $record
+     * @param  array{uri?: string, cid?: string, did?: string, rkey?: string}  $meta  AT Protocol metadata
+     * @return TModel
+     */
+    public function toModel(Data $record, array $meta = []): Model;
+
+    /**
+     * Convert an Eloquent Model to a Record DTO.
+     *
+     * @param  TModel  $model
+     * @return TRecord
+     */
+    public function toRecord(Model $model): Data;
+
+    /**
+     * Update an existing model with data from a record.
+     *
+     * @param  TModel  $model
+     * @param  TRecord  $record
+     * @param  array{uri?: string, cid?: string, did?: string, rkey?: string}  $meta
+     * @return TModel
+     */
+    public function updateModel(Model $model, Data $record, array $meta = []): Model;
+
+    /**
+     * Find or create model from record.
+     *
+     * @param  TRecord  $record
+     * @param  array{uri?: string, cid?: string, did?: string, rkey?: string}  $meta
+     * @return TModel
+     */
+    public function upsert(Data $record, array $meta = []): Model;
+
+    /**
+     * Find model by AT Protocol URI.
+     *
+     * @return TModel|null
+     */
+    public function findByUri(string $uri): ?Model;
+
+    /**
+     * Delete model by AT Protocol URI.
+     */
+    public function deleteByUri(string $uri): bool;
+}

src/Data/Record.php

···
+<?php
+
+namespace SocialDept\AtpParity\Data;
+
+use SocialDept\AtpClient\Contracts\Recordable;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Base class for custom AT Protocol records.
+ *
+ * Extends atp-schema's Data for full compatibility with the ecosystem,
+ * including union type support, validation, equality, and hashing.
+ *
+ * Implements Recordable for seamless atp-client integration.
+ */
+abstract class Record extends Data implements Recordable
+{
+    /**
+     * Get the record type (alias for getLexicon for Recordable interface).
+     */
+    public function getType(): string
+    {
+        return static::getLexicon();
+    }
+}

src/MapperRegistry.php

···
+<?php
+
+namespace SocialDept\AtpParity;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\Contracts\RecordMapper;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Registry for RecordMapper instances.
+ *
+ * Allows looking up mappers by Record class, Model class, or lexicon NSID.
+ */
+class MapperRegistry
+{
+    /** @var array<class-string<Data>, RecordMapper> */
+    protected array $byRecord = [];
+
+    /** @var array<class-string<Model>, RecordMapper> */
+    protected array $byModel = [];
+
+    /** @var array<string, RecordMapper> Keyed by NSID */
+    protected array $byLexicon = [];
+
+    /**
+     * Register a mapper.
+     */
+    public function register(RecordMapper $mapper): void
+    {
+        $recordClass = $mapper->recordClass();
+        $modelClass = $mapper->modelClass();
+
+        $this->byRecord[$recordClass] = $mapper;
+        $this->byModel[$modelClass] = $mapper;
+        $this->byLexicon[$mapper->lexicon()] = $mapper;
+    }
+
+    /**
+     * Get a mapper by Record class.
+     *
+     * @param  class-string<Data>  $recordClass
+     */
+    public function forRecord(string $recordClass): ?RecordMapper
+    {
+        return $this->byRecord[$recordClass] ?? null;
+    }
+
+    /**
+     * Get a mapper by Model class.
+     *
+     * @param  class-string<Model>  $modelClass
+     */
+    public function forModel(string $modelClass): ?RecordMapper
+    {
+        return $this->byModel[$modelClass] ?? null;
+    }
+
+    /**
+     * Get a mapper by lexicon NSID.
+     */
+    public function forLexicon(string $nsid): ?RecordMapper
+    {
+        return $this->byLexicon[$nsid] ?? null;
+    }
+
+    /**
+     * Check if a mapper exists for the given lexicon.
+     */
+    public function hasLexicon(string $nsid): bool
+    {
+        return isset($this->byLexicon[$nsid]);
+    }
+
+    /**
+     * Get all registered lexicon NSIDs.
+     *
+     * @return array<string>
+     */
+    public function lexicons(): array
+    {
+        return array_keys($this->byLexicon);
+    }
+
+    /**
+     * Get all registered mappers.
+     *
+     * @return array<RecordMapper>
+     */
+    public function all(): array
+    {
+        return array_values($this->byLexicon);
+    }
+}

src/RecordMapper.php

···
+<?php
+
+namespace SocialDept\AtpParity;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\Contracts\RecordMapper as RecordMapperContract;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Abstract base class for bidirectional Record <-> Model mapping.
+ *
+ * @template TRecord of Data
+ * @template TModel of Model
+ *
+ * @implements RecordMapperContract<TRecord, TModel>
+ */
+abstract class RecordMapper implements RecordMapperContract
+{
+    /**
+     * Get the Record class this mapper handles.
+     *
+     * @return class-string<TRecord>
+     */
+    abstract public function recordClass(): string;
+
+    /**
+     * Get the Model class this mapper handles.
+     *
+     * @return class-string<TModel>
+     */
+    abstract public function modelClass(): string;
+
+    /**
+     * Map record properties to model attributes.
+     *
+     * @param  TRecord  $record
+     * @return array<string, mixed>
+     */
+    abstract protected function recordToAttributes(Data $record): array;
+
+    /**
+     * Map model attributes to record properties.
+     *
+     * @param  TModel  $model
+     * @return array<string, mixed>
+     */
+    abstract protected function modelToRecordData(Model $model): array;
+
+    /**
+     * Get the lexicon NSID this mapper handles.
+     */
+    public function lexicon(): string
+    {
+        $recordClass = $this->recordClass();
+
+        return $recordClass::getLexicon();
+    }
+
+    /**
+     * Get the column name for storing the AT Protocol URI.
+     */
+    protected function uriColumn(): string
+    {
+        return config('parity.columns.uri', 'atp_uri');
+    }
+
+    /**
+     * Get the column name for storing the AT Protocol CID.
+     */
+    protected function cidColumn(): string
+    {
+        return config('parity.columns.cid', 'atp_cid');
+    }
+
+    public function toModel(Data $record, array $meta = []): Model
+    {
+        $modelClass = $this->modelClass();
+        $attributes = $this->recordToAttributes($record);
+        $attributes = $this->applyMeta($attributes, $meta);
+
+        return new $modelClass($attributes);
+    }
+
+    public function toRecord(Model $model): Data
+    {
+        $recordClass = $this->recordClass();
+
+        return $recordClass::fromArray($this->modelToRecordData($model));
+    }
+
+    public function updateModel(Model $model, Data $record, array $meta = []): Model
+    {
+        $attributes = $this->recordToAttributes($record);
+        $attributes = $this->applyMeta($attributes, $meta);
+        $model->fill($attributes);
+
+        return $model;
+    }
+
+    public function findByUri(string $uri): ?Model
+    {
+        $modelClass = $this->modelClass();
+
+        return $modelClass::where($this->uriColumn(), $uri)->first();
+    }
+
+    public function upsert(Data $record, array $meta = []): Model
+    {
+        $uri = $meta['uri'] ?? null;
+
+        if ($uri) {
+            $existing = $this->findByUri($uri);
+
+            if ($existing) {
+                $this->updateModel($existing, $record, $meta);
+                $existing->save();
+
+                return $existing;
+            }
+        }
+
+        $model = $this->toModel($record, $meta);
+        $model->save();
+
+        return $model;
+    }
+
+    public function deleteByUri(string $uri): bool
+    {
+        $model = $this->findByUri($uri);
+
+        if ($model) {
+            return (bool) $model->delete();
+        }
+
+        return false;
+    }
+
+    /**
+     * Apply AT Protocol metadata to attributes.
+     */
+    protected function applyMeta(array $attributes, array $meta): array
+    {
+        if (isset($meta['uri'])) {
+            $attributes[$this->uriColumn()] = $meta['uri'];
+        }
+
+        if (isset($meta['cid'])) {
+            $attributes[$this->cidColumn()] = $meta['cid'];
+        }
+
+        return $attributes;
+    }
+}