Merge branch 'refs/heads/dev'

.github/workflows/code-style.yml

···
+name: Code Style
+
+on:
+  pull_request:
+    branches: [ main, dev ]
+
+jobs:
+  php-cs-fixer:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.3
+          extensions: gmp, mbstring, json
+          coverage: none
+          tools: php-cs-fixer
+
+      - name: Run PHP CS Fixer
+        run: php-cs-fixer fix --dry-run --diff --verbose

.github/workflows/tests.yml

···
+name: Tests
+
+on:
+  pull_request:
+    branches: [ main, dev ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    name: Tests (PHP 8.2 - Laravel 12)
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.2
+          extensions: gmp, mbstring, json
+          coverage: none
+
+      - name: Install dependencies
+        run: |
+          composer require "laravel/framework:^12.0" "orchestra/testbench:^10.0" --no-interaction --no-update
+          composer update --prefer-stable --prefer-dist --no-interaction
+
+      - name: Execute tests
+        run: vendor/bin/phpunit

.php-cs-fixer.php

···
+<?php
+
+use PhpCsFixer\Config;
+use PhpCsFixer\Finder;
+
+$finder = Finder::create()
+    ->in(__DIR__ . '/src')
+    ->in(__DIR__ . '/tests')
+    ->name('*.php')
+    ->notName('*.blade.php')
+    ->ignoreDotFiles(true)
+    ->ignoreVCS(true);
+
+return (new Config())
+    ->setRules([
+        '@PSR12' => true,
+        'array_syntax' => ['syntax' => 'short'],
+        'ordered_imports' => ['sort_algorithm' => 'alpha'],
+        'no_unused_imports' => true,
+        'not_operator_with_successor_space' => true,
+        'trailing_comma_in_multiline' => true,
+        'phpdoc_scalar' => true,
+        'unary_operator_spaces' => true,
+        'binary_operator_spaces' => true,
+        'blank_line_before_statement' => [
+            'statements' => ['break', 'continue', 'declare', 'return', 'throw', 'try'],
+        ],
+        'phpdoc_single_line_var_spacing' => true,
+        'phpdoc_var_without_name' => true,
+        'method_argument_space' => [
+            'on_multiline' => 'ensure_fully_multiline',
+            'keep_multiple_spaces_after_comma' => true,
+        ],
+    ])
+    ->setFinder($finder);

LICENSE

···
+MIT License
+
+Copyright (c) 2025 Social Dept
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

···
+[![Parity Header](./header.png)](https://github.com/socialdept/atp-parity)
+
+<h3 align="center">
+    Bidirectional mapping between AT Protocol records and Laravel Eloquent models.
+</h3>
+
+<p align="center">
+    <br>
+    <a href="https://packagist.org/packages/socialdept/atp-parity" title="Latest Version on Packagist"><img src="https://img.shields.io/packagist/v/socialdept/atp-parity.svg?style=flat-square"></a>
+    <a href="https://packagist.org/packages/socialdept/atp-parity" title="Total Downloads"><img src="https://img.shields.io/packagist/dt/socialdept/atp-parity.svg?style=flat-square"></a>
+    <a href="https://github.com/socialdept/atp-parity/actions/workflows/tests.yml" title="GitHub Tests Action Status"><img src="https://img.shields.io/github/actions/workflow/status/socialdept/atp-parity/tests.yml?branch=main&label=tests&style=flat-square"></a>
+    <a href="LICENSE" title="Software License"><img src="https://img.shields.io/github/license/socialdept/atp-parity?style=flat-square"></a>
+</p>
+
+---
+
+## What is Parity?
+
+**Parity** is a Laravel package that bridges your Eloquent models with AT Protocol records. It provides bidirectional mapping, automatic firehose synchronization, and type-safe transformations between your database and the decentralized social web.
+
+Think of it as Laravel's model casts, but for AT Protocol records.
+
+## Why use Parity?
+
+- **Laravel-style code** - Familiar patterns you already know
+- **Bidirectional mapping** - Transform records to models and back
+- **Firehose sync** - Automatically sync network events to your database
+- **Type-safe DTOs** - Full integration with atp-schema generated types
+- **Model traits** - Add AT Protocol awareness to any Eloquent model
+- **Flexible mappers** - Define custom transformations for your domain
+
+## Quick Example
+
+```php
+use SocialDept\AtpParity\RecordMapper;
+use SocialDept\AtpSchema\Data\Data;
+use Illuminate\Database\Eloquent\Model;
+
+class PostMapper extends RecordMapper
+{
+    public function recordClass(): string
+    {
+        return \SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post::class;
+    }
+
+    public function modelClass(): string
+    {
+        return \App\Models\Post::class;
+    }
+
+    protected function recordToAttributes(Data $record): array
+    {
+        return [
+            'content' => $record->text,
+            'published_at' => $record->createdAt,
+        ];
+    }
+
+    protected function modelToRecordData(Model $model): array
+    {
+        return [
+            'text' => $model->content,
+            'createdAt' => $model->published_at->toIso8601String(),
+        ];
+    }
+}
+```
+
+## Installation
+
+```bash
+composer require socialdept/atp-parity
+```
+
+Optionally publish the configuration:
+
+```bash
+php artisan vendor:publish --tag=parity-config
+```
+
+## Getting Started
+
+Once installed, you're three steps away from syncing AT Protocol records:
+
+### 1. Create a Mapper
+
+Define how your record maps to your model:
+
+```php
+class PostMapper extends RecordMapper
+{
+    public function recordClass(): string
+    {
+        return Post::class; // Your atp-schema DTO or custom Record
+    }
+
+    public function modelClass(): string
+    {
+        return \App\Models\Post::class;
+    }
+
+    protected function recordToAttributes(Data $record): array
+    {
+        return ['content' => $record->text];
+    }
+
+    protected function modelToRecordData(Model $model): array
+    {
+        return ['text' => $model->content];
+    }
+}
+```
+
+### 2. Register Your Mapper
+
+```php
+// config/parity.php
+return [
+    'mappers' => [
+        App\AtpMappers\PostMapper::class,
+    ],
+];
+```
+
+### 3. Add the Trait to Your Model
+
+```php
+use SocialDept\AtpParity\Concerns\HasAtpRecord;
+
+class Post extends Model
+{
+    use HasAtpRecord;
+}
+```
+
+Your model can now convert to/from AT Protocol records and query by URI.
+
+## What can you build?
+
+- **Data mirrors** - Keep local copies of AT Protocol data
+- **AppViews** - Build custom applications with synced data
+- **Analytics platforms** - Store and analyze network activity
+- **Content aggregators** - Collect and organize posts locally
+- **Moderation tools** - Track and manage content in your database
+- **Hybrid applications** - Combine local and federated data
+
+## Ecosystem Integration
+
+Parity is designed to work seamlessly with the other atp-* packages:
+
+| Package | Integration |
+|---------|-------------|
+| **atp-schema** | Records extend `Data`, use generated DTOs directly |
+| **atp-client** | `RecordHelper` for fetching and hydrating records |
+| **atp-signals** | `ParitySignal` for automatic firehose sync |
+
+### Using with atp-schema
+
+Use generated schema classes directly with `SchemaMapper`:
+
+```php
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post;
+use SocialDept\AtpParity\Support\SchemaMapper;
+
+$mapper = new SchemaMapper(
+    schemaClass: Post::class,
+    modelClass: \App\Models\Post::class,
+    toAttributes: fn(Post $p) => [
+        'content' => $p->text,
+        'published_at' => $p->createdAt,
+    ],
+    toRecordData: fn($m) => [
+        'text' => $m->content,
+        'createdAt' => $m->published_at->toIso8601String(),
+    ],
+);
+
+$registry->register($mapper);
+```
+
+### Using with atp-client
+
+Fetch records by URI and convert directly to models:
+
+```php
+use SocialDept\AtpParity\Support\RecordHelper;
+
+$helper = app(RecordHelper::class);
+
+// Fetch as typed DTO
+$record = $helper->fetch('at://did:plc:xxx/app.bsky.feed.post/abc123');
+
+// Fetch and convert to model (unsaved)
+$post = $helper->fetchAsModel('at://did:plc:xxx/app.bsky.feed.post/abc123');
+
+// Fetch and sync to database (upsert)
+$post = $helper->sync('at://did:plc:xxx/app.bsky.feed.post/abc123');
+```
+
+The helper automatically resolves the DID to find the correct PDS endpoint, so it works with any AT Protocol server - not just Bluesky.
+
+### Using with atp-signals
+
+Enable automatic firehose synchronization by registering the `ParitySignal`:
+
+```php
+// config/signal.php
+return [
+    'signals' => [
+        \SocialDept\AtpParity\Signals\ParitySignal::class,
+    ],
+];
+```
+
+Run `php artisan signal:consume` and your models will automatically sync with matching firehose events.
+
+### Importing Historical Data
+
+For existing records created before you started consuming the firehose:
+
+```bash
+# Import a user's records
+php artisan parity:import did:plc:z72i7hdynmk6r22z27h6tvur
+
+# Check import status
+php artisan parity:import-status
+```
+
+Or programmatically:
+
+```php
+use SocialDept\AtpParity\Import\ImportService;
+
+$service = app(ImportService::class);
+$result = $service->importUser('did:plc:z72i7hdynmk6r22z27h6tvur');
+
+echo "Synced {$result->recordsSynced} records";
+```
+
+## Documentation
+
+For detailed documentation on specific topics:
+
+- [Record Mappers](docs/mappers.md) - Creating and using mappers
+- [Model Traits](docs/traits.md) - HasAtpRecord and SyncsWithAtp
+- [atp-schema Integration](docs/atp-schema-integration.md) - Using generated DTOs
+- [atp-client Integration](docs/atp-client-integration.md) - RecordHelper and fetching
+- [atp-signals Integration](docs/atp-signals-integration.md) - ParitySignal and firehose sync
+- [Importing](docs/importing.md) - Syncing historical data
+
+## Model Traits
+
+### HasAtpRecord
+
+Add AT Protocol awareness to your models:
+
+```php
+use SocialDept\AtpParity\Concerns\HasAtpRecord;
+
+class Post extends Model
+{
+    use HasAtpRecord;
+
+    protected $fillable = ['content', 'atp_uri', 'atp_cid'];
+}
+```
+
+Available methods:
+
+```php
+// Get AT Protocol metadata
+$post->getAtpUri();        // at://did:plc:xxx/app.bsky.feed.post/rkey
+$post->getAtpCid();        // bafyre...
+$post->getAtpDid();        // did:plc:xxx (extracted from URI)
+$post->getAtpCollection(); // app.bsky.feed.post (extracted from URI)
+$post->getAtpRkey();       // rkey (extracted from URI)
+
+// Check sync status
+$post->hasAtpRecord();     // true if synced
+
+// Convert to record DTO
+$record = $post->toAtpRecord();
+
+// Query scopes
+Post::withAtpRecord()->get();      // Only synced posts
+Post::withoutAtpRecord()->get();   // Only unsynced posts
+Post::whereAtpUri($uri)->first();  // Find by URI
+```
+
+### SyncsWithAtp
+
+Extended trait for bidirectional sync tracking:
+
+```php
+use SocialDept\AtpParity\Concerns\SyncsWithAtp;
+
+class Post extends Model
+{
+    use SyncsWithAtp;
+}
+```
+
+Additional methods:
+
+```php
+// Track sync status
+$post->getAtpSyncedAt();   // Last sync timestamp
+$post->hasLocalChanges();  // True if updated since last sync
+
+// Mark as synced
+$post->markAsSynced($uri, $cid);
+
+// Update from remote
+$post->updateFromRecord($record, $uri, $cid);
+```
+
+## Database Migration
+
+Add AT Protocol columns to your models:
+
+```php
+Schema::table('posts', function (Blueprint $table) {
+    $table->string('atp_uri')->nullable()->unique();
+    $table->string('atp_cid')->nullable();
+    $table->timestamp('atp_synced_at')->nullable(); // For SyncsWithAtp
+});
+```
+
+## Configuration
+
+```php
+// config/parity.php
+return [
+    // Registered mappers
+    'mappers' => [
+        App\AtpMappers\PostMapper::class,
+        App\AtpMappers\ProfileMapper::class,
+    ],
+
+    // Column names for AT Protocol metadata
+    'columns' => [
+        'uri' => 'atp_uri',
+        'cid' => 'atp_cid',
+    ],
+];
+```
+
+## Creating Custom Records
+
+Extend the `Record` base class for custom AT Protocol records:
+
+```php
+use SocialDept\AtpParity\Data\Record;
+use Carbon\Carbon;
+
+class PostRecord extends Record
+{
+    public function __construct(
+        public readonly string $text,
+        public readonly Carbon $createdAt,
+        public readonly ?array $facets = null,
+    ) {}
+
+    public static function getLexicon(): string
+    {
+        return 'app.bsky.feed.post';
+    }
+
+    public static function fromArray(array $data): static
+    {
+        return new static(
+            text: $data['text'],
+            createdAt: Carbon::parse($data['createdAt']),
+            facets: $data['facets'] ?? null,
+        );
+    }
+}
+```
+
+The `Record` class extends `atp-schema`'s `Data` and implements `atp-client`'s `Recordable` interface, ensuring full compatibility with the ecosystem.
+
+## Requirements
+
+- PHP 8.2+
+- Laravel 10, 11, or 12
+- [socialdept/atp-schema](https://github.com/socialdept/atp-schema) ^0.3
+- [socialdept/atp-client](https://github.com/socialdept/atp-client) ^0.0
+- [socialdept/atp-resolver](https://github.com/socialdept/atp-resolver) ^1.1
+- [socialdept/atp-signals](https://github.com/socialdept/atp-signals) ^1.1
+
+## Testing
+
+```bash
+composer test
+```
+
+## Resources
+
+- [AT Protocol Documentation](https://atproto.com/)
+- [Bluesky API Docs](https://docs.bsky.app/)
+- [atp-schema](https://github.com/socialdept/atp-schema) - Generated AT Protocol DTOs
+- [atp-client](https://github.com/socialdept/atp-client) - AT Protocol HTTP client
+- [atp-signals](https://github.com/socialdept/atp-signals) - Firehose event consumer
+
+## Support & Contributing
+
+Found a bug or have a feature request? [Open an issue](https://github.com/socialdept/atp-parity/issues).
+
+Want to contribute? Check out the [contribution guidelines](contributing.md).
+
+## Changelog
+
+Please see [changelog](changelog.md) for recent changes.
+
+## Credits
+
+- [Miguel Batres](https://batres.co) - founder & lead maintainer
+- [All contributors](https://github.com/socialdept/atp-parity/graphs/contributors)
+
+## License
+
+Parity is open-source software licensed under the [MIT license](license.md).
+
+---
+
+**Built for the Federation** - By Social Dept.

changelog.md

···
-# Changelog
-
-All notable changes to `AtpReplicator` will be documented in this file.
-
-## Version 1.0
-
-### Added
-- Everything

composer.json

···
 {
     "name": "socialdept/atp-parity",
-    "description": ":package_description",
+    "description": "AT Protocol record mapping and sync for Laravel Eloquent models",
     "license": "MIT",
     "authors": [
         {
···
         }
     ],
     "homepage": "https://github.com/socialdept/atp-parity",
-    "keywords": ["Laravel", "AtpReplicator"],
+    "keywords": ["Laravel", "AT Protocol", "Bluesky", "ATP", "Parity", "Sync"],
     "require": {
-        "illuminate/support": "~9"
+        "php": "^8.2",
+        "illuminate/support": "^10.0|^11.0|^12.0",
+        "illuminate/database": "^10.0|^11.0|^12.0",
+        "socialdept/atp-schema": "^0.3",
+        "socialdept/atp-client": "^0.0",
+        "socialdept/atp-resolver": "^1.1",
+        "socialdept/atp-signals": "^1.1"
     },
     "require-dev": {
-        "../../../vendor/phpunit/phpunit": "~9.0",
-        "orchestra/testbench": "~7"
+        "phpunit/phpunit": "^10.0|^11.0",
+        "orchestra/testbench": "^8.0|^9.0|^10.0"
     },
     "autoload": {
         "psr-4": {
-            "SocialDept\\AtpReplicator\\": "src/"
+            "SocialDept\\AtpParity\\": "src/"
         }
     },
     "autoload-dev": {
         "psr-4": {
-            "SocialDept\\AtpReplicator\\Tests\\": "tests"
+            "SocialDept\\AtpParity\\Tests\\": "tests"
         }
     },
     "extra": {
         "laravel": {
             "providers": [
-                "SocialDept\\AtpReplicator\\AtpReplicatorServiceProvider"
+                "SocialDept\\AtpParity\\ParityServiceProvider"
             ],
             "aliases": {
-                "AtpReplicator": "SocialDept\\AtpReplicator\\Facades\\AtpReplicator"
+                "Parity": "SocialDept\\AtpParity\\Facades\\Parity"
             }
         }
     }

config/atp-replicator.php

···
-<?php
-
-return [
-    //
-];

config/parity.php

···
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Record Mappers
+    |--------------------------------------------------------------------------
+    |
+    | List of RecordMapper classes to automatically register. Each mapper
+    | handles bidirectional conversion between an AT Protocol record DTO
+    | and an Eloquent model.
+    |
+    */
+    'mappers' => [
+        // App\AtpMappers\PostMapper::class,
+        // App\AtpMappers\ProfileMapper::class,
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | AT Protocol Metadata Columns
+    |--------------------------------------------------------------------------
+    |
+    | The column names used to store AT Protocol metadata on models.
+    |
+    */
+    'columns' => [
+        'uri' => 'atp_uri',
+        'cid' => 'atp_cid',
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Import Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Settings for importing historical AT Protocol records to your database.
+    |
+    */
+    'import' => [
+        // Records per page when listing from PDS
+        'page_size' => 100,
+
+        // Delay between pages in milliseconds (rate limiting)
+        'page_delay' => 100,
+
+        // Queue name for import jobs
+        'queue' => 'default',
+
+        // Database table for storing import state
+        'state_table' => 'parity_import_states',
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Sync Filtering
+    |--------------------------------------------------------------------------
+    |
+    | Control which firehose events get synced to your database.
+    |
+    */
+    'sync' => [
+        // Only sync records from these DIDs (null = all DIDs)
+        'dids' => null,
+
+        // Only sync these operations: 'create', 'update', 'delete' (null = all)
+        'operations' => null,
+
+        // Custom filter callback: function(SignalEvent $event): bool
+        // Return true to sync the event, false to skip it
+        'filter' => null,
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Conflict Resolution
+    |--------------------------------------------------------------------------
+    |
+    | Strategy for handling conflicts between local and remote changes.
+    |
+    */
+    'conflicts' => [
+        // Strategy: 'remote', 'local', 'newest', 'manual'
+        'strategy' => env('PARITY_CONFLICT_STRATEGY', 'remote'),
+
+        // Database table for pending conflicts (manual resolution)
+        'table' => 'parity_conflicts',
+
+        // Notifiable class or callback for conflict notifications
+        'notify' => null,
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Collection Discovery
+    |--------------------------------------------------------------------------
+    |
+    | Settings for discovering users with records in specific collections.
+    |
+    */
+    'discovery' => [
+        // Relay URL for discovery queries
+        'relay' => env('ATP_RELAY_URL', 'https://bsky.network'),
+    ],
+];

contributing.md CONTRIBUTING.md

···
 
 Contributions are welcome and will be fully credited.
 
-Contributions are accepted via Pull Requests on [Github](https://github.com/socialdept/atp-parity).
+Contributions are accepted via Pull Requests on [Github](https://github.com/social-dept/beacon).
 
 # Things you could do
 If you want to contribute but do not know where to start, this list provides some starting points.

database/migrations/create_parity_conflicts_table.php

···
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $table = config('parity.conflicts.table', 'parity_conflicts');
+
+        Schema::create($table, function (Blueprint $table) {
+            $table->id();
+            $table->string('model_type');
+            $table->unsignedBigInteger('model_id');
+            $table->string('uri')->nullable();
+            $table->json('local_data');
+            $table->json('remote_data');
+            $table->string('status')->default('pending');
+            $table->string('resolution')->nullable();
+            $table->timestamp('resolved_at')->nullable();
+            $table->timestamps();
+
+            $table->index(['model_type', 'model_id']);
+            $table->index('status');
+            $table->index('uri');
+        });
+    }
+
+    public function down(): void
+    {
+        $table = config('parity.conflicts.table', 'parity_conflicts');
+
+        Schema::dropIfExists($table);
+    }
+};

database/migrations/create_parity_import_states_table.php

···
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $table = config('parity.import.state_table', 'parity_import_states');
+
+        Schema::create($table, function (Blueprint $table) {
+            $table->id();
+            $table->string('did');
+            $table->string('collection');
+            $table->string('status')->default('pending');
+            $table->string('cursor')->nullable();
+            $table->unsignedInteger('records_synced')->default(0);
+            $table->unsignedInteger('records_skipped')->default(0);
+            $table->unsignedInteger('records_failed')->default(0);
+            $table->timestamp('started_at')->nullable();
+            $table->timestamp('completed_at')->nullable();
+            $table->text('error')->nullable();
+            $table->timestamps();
+
+            $table->unique(['did', 'collection']);
+            $table->index('status');
+        });
+    }
+
+    public function down(): void
+    {
+        $table = config('parity.import.state_table', 'parity_import_states');
+
+        Schema::dropIfExists($table);
+    }
+};

docs/atp-client-integration.md

···
+# atp-client Integration
+
+Parity integrates with atp-client to fetch records from the AT Protocol network and convert them to Eloquent models. The `RecordHelper` class provides a simple interface for these operations.
+
+## RecordHelper
+
+The `RecordHelper` is registered as a singleton and available via the container:
+
+```php
+use SocialDept\AtpParity\Support\RecordHelper;
+
+$helper = app(RecordHelper::class);
+```
+
+### How It Works
+
+When you provide an AT Protocol URI, RecordHelper:
+
+1. Parses the URI to extract the DID, collection, and rkey
+2. Resolves the DID to find the user's PDS endpoint (via atp-resolver)
+3. Creates a public client for that PDS
+4. Fetches the record
+5. Converts it using the registered mapper
+
+This means it works with any AT Protocol server, not just Bluesky.
+
+## Fetching Records
+
+### `fetch(string $uri, ?string $recordClass = null): mixed`
+
+Fetches a record and returns it as a typed DTO.
+
+```php
+use SocialDept\AtpParity\Support\RecordHelper;
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post;
+
+$helper = app(RecordHelper::class);
+
+// Auto-detect type from registered mapper
+$record = $helper->fetch('at://did:plc:abc123/app.bsky.feed.post/xyz789');
+
+// Or specify the class explicitly
+$record = $helper->fetch(
+    'at://did:plc:abc123/app.bsky.feed.post/xyz789',
+    Post::class
+);
+
+// Access typed properties
+echo $record->text;
+echo $record->createdAt;
+```
+
+### `fetchAsModel(string $uri): ?Model`
+
+Fetches a record and converts it to an Eloquent model (unsaved).
+
+```php
+$post = $helper->fetchAsModel('at://did:plc:abc123/app.bsky.feed.post/xyz789');
+
+if ($post) {
+    echo $post->content;
+    echo $post->atp_uri;
+    echo $post->atp_cid;
+
+    // Save if you want to persist it
+    $post->save();
+}
+```
+
+Returns `null` if no mapper is registered for the collection.
+
+### `sync(string $uri): ?Model`
+
+Fetches a record and upserts it to the database.
+
+```php
+// Creates or updates the model
+$post = $helper->sync('at://did:plc:abc123/app.bsky.feed.post/xyz789');
+
+// Model is saved automatically
+echo $post->id;
+echo $post->content;
+```
+
+This is the most common method for syncing remote records to your database.
+
+## Working with Responses
+
+### `hydrateRecord(GetRecordResponse $response, ?string $recordClass = null): mixed`
+
+If you already have a `GetRecordResponse` from atp-client, convert it to a typed DTO:
+
+```php
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\Support\RecordHelper;
+
+$helper = app(RecordHelper::class);
+
+// Using atp-client directly
+$client = Atp::public();
+$response = $client->atproto->repo->getRecord(
+    'did:plc:abc123',
+    'app.bsky.feed.post',
+    'xyz789'
+);
+
+// Convert to typed DTO
+$record = $helper->hydrateRecord($response);
+```
+
+## Practical Examples
+
+### Syncing a Single Post
+
+```php
+$helper = app(RecordHelper::class);
+
+$uri = 'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3k2yihcrp6f2c';
+$post = $helper->sync($uri);
+
+echo "Synced: {$post->content}";
+```
+
+### Syncing Multiple Posts
+
+```php
+$helper = app(RecordHelper::class);
+
+$uris = [
+    'at://did:plc:abc/app.bsky.feed.post/123',
+    'at://did:plc:def/app.bsky.feed.post/456',
+    'at://did:plc:ghi/app.bsky.feed.post/789',
+];
+
+foreach ($uris as $uri) {
+    try {
+        $post = $helper->sync($uri);
+        echo "Synced: {$post->id}\n";
+    } catch (\Exception $e) {
+        echo "Failed to sync {$uri}: {$e->getMessage()}\n";
+    }
+}
+```
+
+### Fetching for Preview (Without Saving)
+
+```php
+$helper = app(RecordHelper::class);
+
+// Get model without saving
+$post = $helper->fetchAsModel('at://did:plc:xxx/app.bsky.feed.post/abc');
+
+if ($post) {
+    return view('posts.preview', ['post' => $post]);
+}
+
+return abort(404);
+```
+
+### Checking if Record Exists Locally
+
+```php
+use App\Models\Post;
+use SocialDept\AtpParity\Support\RecordHelper;
+
+$uri = 'at://did:plc:xxx/app.bsky.feed.post/abc';
+
+// Check local database first
+$post = Post::whereAtpUri($uri)->first();
+
+if (!$post) {
+    // Not in database, fetch from network
+    $helper = app(RecordHelper::class);
+    $post = $helper->sync($uri);
+}
+
+return $post;
+```
+
+### Building a Post Importer
+
+```php
+namespace App\Services;
+
+use SocialDept\AtpParity\Support\RecordHelper;
+use SocialDept\AtpClient\Facades\Atp;
+
+class PostImporter
+{
+    public function __construct(
+        protected RecordHelper $helper
+    ) {}
+
+    /**
+     * Import all posts from a user.
+     */
+    public function importUserPosts(string $did, int $limit = 100): array
+    {
+        $imported = [];
+        $client = Atp::public();
+        $cursor = null;
+
+        do {
+            $response = $client->atproto->repo->listRecords(
+                repo: $did,
+                collection: 'app.bsky.feed.post',
+                limit: min($limit - count($imported), 100),
+                cursor: $cursor
+            );
+
+            foreach ($response->records as $record) {
+                $post = $this->helper->sync($record->uri);
+                $imported[] = $post;
+
+                if (count($imported) >= $limit) {
+                    break 2;
+                }
+            }
+
+            $cursor = $response->cursor;
+        } while ($cursor && count($imported) < $limit);
+
+        return $imported;
+    }
+}
+```
+
+## Error Handling
+
+RecordHelper returns `null` for various failure conditions:
+
+```php
+$helper = app(RecordHelper::class);
+
+// Invalid URI format
+$result = $helper->fetch('not-a-valid-uri');
+// Returns null
+
+// No mapper registered for collection
+$result = $helper->fetchAsModel('at://did:plc:xxx/some.unknown.collection/abc');
+// Returns null
+
+// PDS resolution failed
+$result = $helper->fetch('at://did:plc:invalid/app.bsky.feed.post/abc');
+// Returns null (or throws exception depending on resolver config)
+```
+
+For more control, catch exceptions:
+
+```php
+use SocialDept\AtpResolver\Exceptions\DidResolutionException;
+
+try {
+    $post = $helper->sync($uri);
+} catch (DidResolutionException $e) {
+    // DID could not be resolved
+    Log::warning("Could not resolve DID for {$uri}");
+} catch (\Exception $e) {
+    // Network error, invalid response, etc.
+    Log::error("Failed to sync {$uri}: {$e->getMessage()}");
+}
+```
+
+## Performance Considerations
+
+### PDS Client Caching
+
+RecordHelper caches public clients by PDS endpoint:
+
+```php
+// First request to this PDS - creates client
+$helper->sync('at://did:plc:abc/app.bsky.feed.post/1');
+
+// Same PDS - reuses cached client
+$helper->sync('at://did:plc:abc/app.bsky.feed.post/2');
+
+// Different PDS - creates new client
+$helper->sync('at://did:plc:xyz/app.bsky.feed.post/1');
+```
+
+### DID Resolution Caching
+
+atp-resolver caches DID documents and PDS endpoints. Default TTL is 1 hour.
+
+### Batch Operations
+
+For bulk imports, consider using atp-client's `listRecords` directly and then batch-processing:
+
+```php
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\MapperRegistry;
+
+$client = Atp::public($pdsEndpoint);
+$registry = app(MapperRegistry::class);
+$mapper = $registry->forLexicon('app.bsky.feed.post');
+
+$response = $client->atproto->repo->listRecords(
+    repo: $did,
+    collection: 'app.bsky.feed.post',
+    limit: 100
+);
+
+foreach ($response->records as $record) {
+    $recordClass = $mapper->recordClass();
+    $dto = $recordClass::fromArray($record->value);
+
+    $mapper->upsert($dto, [
+        'uri' => $record->uri,
+        'cid' => $record->cid,
+    ]);
+}
+```
+
+## Using with Authenticated Client
+
+While RecordHelper uses public clients, you can also use authenticated clients for records that require auth:
+
+```php
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\MapperRegistry;
+
+// Authenticated client
+$client = Atp::as('user.bsky.social');
+
+// Fetch a record that requires auth
+$response = $client->atproto->repo->getRecord(
+    repo: $client->session()->did(),
+    collection: 'app.bsky.feed.post',
+    rkey: 'abc123'
+);
+
+// Convert using mapper
+$registry = app(MapperRegistry::class);
+$mapper = $registry->forLexicon('app.bsky.feed.post');
+
+$recordClass = $mapper->recordClass();
+$record = $recordClass::fromArray($response->value);
+
+$model = $mapper->upsert($record, [
+    'uri' => $response->uri,
+    'cid' => $response->cid,
+]);
+```

docs/atp-schema-integration.md

···
+# atp-schema Integration
+
+Parity is built on top of atp-schema, using its `Data` base class for all record DTOs. This provides type safety, validation, and compatibility with the AT Protocol ecosystem.
+
+## How It Works
+
+The `SocialDept\AtpParity\Data\Record` class extends `SocialDept\AtpSchema\Data\Data`:
+
+```php
+namespace SocialDept\AtpParity\Data;
+
+use SocialDept\AtpClient\Contracts\Recordable;
+use SocialDept\AtpSchema\Data\Data;
+
+abstract class Record extends Data implements Recordable
+{
+    public function getType(): string
+    {
+        return static::getLexicon();
+    }
+}
+```
+
+This means all Parity records inherit:
+
+- `getLexicon()` - Returns the lexicon NSID
+- `fromArray()` - Creates instance from array data
+- `toArray()` - Converts to array
+- `toRecord()` - Converts to record format for API calls
+- Type validation and casting
+
+## Using Generated Schema Classes
+
+atp-schema generates PHP classes for all AT Protocol lexicons. Use them directly with Parity:
+
+```php
+use SocialDept\AtpParity\Support\SchemaMapper;
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post;
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Like;
+use SocialDept\AtpSchema\Generated\App\Bsky\Graph\Follow;
+
+// Post mapper
+$postMapper = new SchemaMapper(
+    schemaClass: Post::class,
+    modelClass: \App\Models\Post::class,
+    toAttributes: fn(Post $post) => [
+        'content' => $post->text,
+        'published_at' => $post->createdAt,
+        'langs' => $post->langs,
+        'reply_parent' => $post->reply?->parent->uri,
+        'reply_root' => $post->reply?->root->uri,
+    ],
+    toRecordData: fn($model) => [
+        'text' => $model->content,
+        'createdAt' => $model->published_at->toIso8601String(),
+        'langs' => $model->langs ?? ['en'],
+    ],
+);
+
+// Like mapper
+$likeMapper = new SchemaMapper(
+    schemaClass: Like::class,
+    modelClass: \App\Models\Like::class,
+    toAttributes: fn(Like $like) => [
+        'subject_uri' => $like->subject->uri,
+        'subject_cid' => $like->subject->cid,
+        'liked_at' => $like->createdAt,
+    ],
+    toRecordData: fn($model) => [
+        'subject' => [
+            'uri' => $model->subject_uri,
+            'cid' => $model->subject_cid,
+        ],
+        'createdAt' => $model->liked_at->toIso8601String(),
+    ],
+);
+
+// Follow mapper
+$followMapper = new SchemaMapper(
+    schemaClass: Follow::class,
+    modelClass: \App\Models\Follow::class,
+    toAttributes: fn(Follow $follow) => [
+        'subject_did' => $follow->subject,
+        'followed_at' => $follow->createdAt,
+    ],
+    toRecordData: fn($model) => [
+        'subject' => $model->subject_did,
+        'createdAt' => $model->followed_at->toIso8601String(),
+    ],
+);
+```
+
+## Creating Custom Records
+
+For custom lexicons or when you need more control, extend the `Record` class:
+
+```php
+<?php
+
+namespace App\AtpRecords;
+
+use Carbon\Carbon;
+use SocialDept\AtpParity\Data\Record;
+
+class CustomPost extends Record
+{
+    public function __construct(
+        public readonly string $text,
+        public readonly Carbon $createdAt,
+        public readonly ?array $facets = null,
+        public readonly ?array $embed = null,
+        public readonly ?array $langs = null,
+    ) {}
+
+    public static function getLexicon(): string
+    {
+        return 'app.bsky.feed.post';
+    }
+
+    public static function fromArray(array $data): static
+    {
+        return new static(
+            text: $data['text'],
+            createdAt: Carbon::parse($data['createdAt']),
+            facets: $data['facets'] ?? null,
+            embed: $data['embed'] ?? null,
+            langs: $data['langs'] ?? null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return array_filter([
+            '$type' => static::getLexicon(),
+            'text' => $this->text,
+            'createdAt' => $this->createdAt->toIso8601String(),
+            'facets' => $this->facets,
+            'embed' => $this->embed,
+            'langs' => $this->langs,
+        ], fn($v) => $v !== null);
+    }
+}
+```
+
+## Custom Lexicons (AppView)
+
+Building a custom AT Protocol application? Define your own lexicons:
+
+```php
+<?php
+
+namespace App\AtpRecords;
+
+use Carbon\Carbon;
+use SocialDept\AtpParity\Data\Record;
+
+class Article extends Record
+{
+    public function __construct(
+        public readonly string $title,
+        public readonly string $body,
+        public readonly Carbon $publishedAt,
+        public readonly ?array $tags = null,
+        public readonly ?string $coverImage = null,
+    ) {}
+
+    public static function getLexicon(): string
+    {
+        return 'com.myapp.blog.article'; // Your custom NSID
+    }
+
+    public static function fromArray(array $data): static
+    {
+        return new static(
+            title: $data['title'],
+            body: $data['body'],
+            publishedAt: Carbon::parse($data['publishedAt']),
+            tags: $data['tags'] ?? null,
+            coverImage: $data['coverImage'] ?? null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return array_filter([
+            '$type' => static::getLexicon(),
+            'title' => $this->title,
+            'body' => $this->body,
+            'publishedAt' => $this->publishedAt->toIso8601String(),
+            'tags' => $this->tags,
+            'coverImage' => $this->coverImage,
+        ], fn($v) => $v !== null);
+    }
+}
+```
+
+## Working with Embedded Types
+
+atp-schema generates classes for embedded types. Use them in your mappings:
+
+```php
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post;
+use SocialDept\AtpSchema\Generated\App\Bsky\Embed\Images;
+use SocialDept\AtpSchema\Generated\App\Bsky\Embed\External;
+use SocialDept\AtpSchema\Generated\Com\Atproto\Repo\StrongRef;
+
+$mapper = new SchemaMapper(
+    schemaClass: Post::class,
+    modelClass: \App\Models\Post::class,
+    toAttributes: fn(Post $post) => [
+        'content' => $post->text,
+        'published_at' => $post->createdAt,
+        'has_images' => $post->embed instanceof Images,
+        'has_link' => $post->embed instanceof External,
+        'embed_data' => $post->embed?->toArray(),
+    ],
+    toRecordData: fn($model) => [
+        'text' => $model->content,
+        'createdAt' => $model->published_at->toIso8601String(),
+    ],
+);
+```
+
+## Handling Union Types
+
+AT Protocol uses union types for fields like `embed`. atp-schema handles these via discriminated unions:
+
+```php
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post;
+use SocialDept\AtpSchema\Generated\App\Bsky\Embed\Images;
+use SocialDept\AtpSchema\Generated\App\Bsky\Embed\External;
+use SocialDept\AtpSchema\Generated\App\Bsky\Embed\Record;
+use SocialDept\AtpSchema\Generated\App\Bsky\Embed\RecordWithMedia;
+
+$toAttributes = function(Post $post): array {
+    $attributes = [
+        'content' => $post->text,
+        'published_at' => $post->createdAt,
+    ];
+
+    // Handle embed union type
+    if ($post->embed) {
+        match (true) {
+            $post->embed instanceof Images => $attributes['embed_type'] = 'images',
+            $post->embed instanceof External => $attributes['embed_type'] = 'external',
+            $post->embed instanceof Record => $attributes['embed_type'] = 'quote',
+            $post->embed instanceof RecordWithMedia => $attributes['embed_type'] = 'quote_media',
+            default => $attributes['embed_type'] = 'unknown',
+        };
+        $attributes['embed_data'] = $post->embed->toArray();
+    }
+
+    return $attributes;
+};
+```
+
+## Reply Threading
+
+Posts can be replies to other posts:
+
+```php
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post;
+
+$toAttributes = function(Post $post): array {
+    $attributes = [
+        'content' => $post->text,
+        'published_at' => $post->createdAt,
+        'is_reply' => $post->reply !== null,
+    ];
+
+    if ($post->reply) {
+        // Parent is the immediate post being replied to
+        $attributes['reply_parent_uri'] = $post->reply->parent->uri;
+        $attributes['reply_parent_cid'] = $post->reply->parent->cid;
+
+        // Root is the top of the thread
+        $attributes['reply_root_uri'] = $post->reply->root->uri;
+        $attributes['reply_root_cid'] = $post->reply->root->cid;
+    }
+
+    return $attributes;
+};
+```
+
+## Facets (Rich Text)
+
+Posts with mentions, links, and hashtags use facets:
+
+```php
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post;
+use SocialDept\AtpSchema\Generated\App\Bsky\Richtext\Facet;
+
+$toAttributes = function(Post $post): array {
+    $attributes = [
+        'content' => $post->text,
+        'published_at' => $post->createdAt,
+    ];
+
+    // Extract mentions, links, and tags from facets
+    $mentions = [];
+    $links = [];
+    $tags = [];
+
+    foreach ($post->facets ?? [] as $facet) {
+        foreach ($facet->features as $feature) {
+            $type = $feature->getType();
+            match ($type) {
+                'app.bsky.richtext.facet#mention' => $mentions[] = $feature->did,
+                'app.bsky.richtext.facet#link' => $links[] = $feature->uri,
+                'app.bsky.richtext.facet#tag' => $tags[] = $feature->tag,
+                default => null,
+            };
+        }
+    }
+
+    $attributes['mentions'] = $mentions;
+    $attributes['links'] = $links;
+    $attributes['tags'] = $tags;
+    $attributes['facets'] = $post->facets; // Store raw for reconstruction
+
+    return $attributes;
+};
+```
+
+## Type Safety Benefits
+
+Using atp-schema classes provides:
+
+1. **IDE Autocompletion** - Full property and method suggestions
+2. **Type Checking** - Static analysis catches errors
+3. **Validation** - Data is validated on construction
+4. **Documentation** - Generated classes include docblocks
+
+```php
+// IDE knows $post->text is string, $post->createdAt is string, etc.
+$toAttributes = function(Post $post): array {
+    return [
+        'content' => $post->text,           // string
+        'published_at' => $post->createdAt, // string (ISO 8601)
+        'langs' => $post->langs,            // ?array
+        'facets' => $post->facets,          // ?array
+    ];
+};
+```
+
+## Regenerating Schema Classes
+
+When the AT Protocol schema updates, regenerate the classes:
+
+```bash
+# In the atp-schema package
+php artisan atp:generate
+```
+
+Your mappers will automatically work with the updated types.

docs/atp-signals-integration.md

···
+# atp-signals Integration
+
+Parity integrates with atp-signals to automatically sync firehose events to your Eloquent models in real-time. The `ParitySignal` class handles create, update, and delete operations for all registered mappers.
+
+## ParitySignal
+
+The `ParitySignal` is a pre-built signal that listens for commit events and syncs them to your database using your registered mappers.
+
+### How It Works
+
+1. ParitySignal listens for `commit` events on the firehose
+2. It filters for collections that have registered mappers
+3. For each matching event:
+   - **Create/Update**: Upserts the record to your database
+   - **Delete**: Removes the record from your database
+
+### Setup
+
+Register the signal in your atp-signals config:
+
+```php
+// config/signal.php
+return [
+    'signals' => [
+        \SocialDept\AtpParity\Signals\ParitySignal::class,
+    ],
+];
+```
+
+Then start consuming:
+
+```bash
+php artisan signal:consume
+```
+
+That's it. Your models will automatically sync with the firehose.
+
+## What Gets Synced
+
+ParitySignal only syncs collections that have registered mappers:
+
+```php
+// config/parity.php
+return [
+    'mappers' => [
+        App\AtpMappers\PostMapper::class,    // app.bsky.feed.post
+        App\AtpMappers\LikeMapper::class,    // app.bsky.feed.like
+        App\AtpMappers\FollowMapper::class,  // app.bsky.graph.follow
+    ],
+];
+```
+
+With this config, ParitySignal will sync posts, likes, and follows. All other collections are ignored.
+
+## Event Flow
+
+```
+Firehose Event
+      ↓
+ParitySignal.handle()
+      ↓
+Check: Is collection registered?
+      ↓
+   Yes → Get mapper for collection
+      ↓
+Create DTO from event record
+      ↓
+Call mapper.upsert() or mapper.deleteByUri()
+      ↓
+Model saved to database
+```
+
+## Example: Syncing Posts
+
+### 1. Create the Model
+
+```php
+// app/Models/Post.php
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\Concerns\SyncsWithAtp;
+
+class Post extends Model
+{
+    use SyncsWithAtp;
+
+    protected $fillable = [
+        'content',
+        'author_did',
+        'published_at',
+        'atp_uri',
+        'atp_cid',
+        'atp_synced_at',
+    ];
+
+    protected $casts = [
+        'published_at' => 'datetime',
+        'atp_synced_at' => 'datetime',
+    ];
+}
+```
+
+### 2. Create the Migration
+
+```php
+Schema::create('posts', function (Blueprint $table) {
+    $table->id();
+    $table->text('content');
+    $table->string('author_did');
+    $table->timestamp('published_at');
+    $table->string('atp_uri')->unique();
+    $table->string('atp_cid');
+    $table->timestamp('atp_synced_at')->nullable();
+    $table->timestamps();
+});
+```
+
+### 3. Create the Mapper
+
+```php
+// app/AtpMappers/PostMapper.php
+namespace App\AtpMappers;
+
+use App\Models\Post;
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\RecordMapper;
+use SocialDept\AtpSchema\Data\Data;
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post as PostRecord;
+
+class PostMapper extends RecordMapper
+{
+    public function recordClass(): string
+    {
+        return PostRecord::class;
+    }
+
+    public function modelClass(): string
+    {
+        return Post::class;
+    }
+
+    protected function recordToAttributes(Data $record): array
+    {
+        return [
+            'content' => $record->text,
+            'published_at' => $record->createdAt,
+        ];
+    }
+
+    protected function modelToRecordData(Model $model): array
+    {
+        return [
+            'text' => $model->content,
+            'createdAt' => $model->published_at->toIso8601String(),
+        ];
+    }
+}
+```
+
+### 4. Register Everything
+
+```php
+// config/parity.php
+return [
+    'mappers' => [
+        App\AtpMappers\PostMapper::class,
+    ],
+];
+```
+
+```php
+// config/signal.php
+return [
+    'signals' => [
+        \SocialDept\AtpParity\Signals\ParitySignal::class,
+    ],
+];
+```
+
+### 5. Start Syncing
+
+```bash
+php artisan signal:consume
+```
+
+Every new post on the AT Protocol network will now be saved to your `posts` table.
+
+## Filtering by User
+
+To only sync records from specific users, create a custom signal:
+
+```php
+namespace App\Signals;
+
+use SocialDept\AtpParity\Signals\ParitySignal;
+use SocialDept\AtpSignals\Events\SignalEvent;
+
+class FilteredParitySignal extends ParitySignal
+{
+    /**
+     * DIDs to sync.
+     */
+    protected array $allowedDids = [
+        'did:plc:abc123',
+        'did:plc:def456',
+    ];
+
+    public function handle(SignalEvent $event): void
+    {
+        // Only process events from allowed DIDs
+        if (!in_array($event->did, $this->allowedDids)) {
+            return;
+        }
+
+        parent::handle($event);
+    }
+}
+```
+
+Register your custom signal instead:
+
+```php
+// config/signal.php
+return [
+    'signals' => [
+        App\Signals\FilteredParitySignal::class,
+    ],
+];
+```
+
+## Filtering by Collection
+
+To only sync specific collections (even if more mappers are registered):
+
+```php
+namespace App\Signals;
+
+use SocialDept\AtpParity\Signals\ParitySignal;
+
+class PostsOnlySignal extends ParitySignal
+{
+    public function collections(): ?array
+    {
+        // Only sync posts, ignore other registered mappers
+        return ['app.bsky.feed.post'];
+    }
+}
+```
+
+## Custom Processing
+
+Add custom logic before or after syncing:
+
+```php
+namespace App\Signals;
+
+use SocialDept\AtpParity\Contracts\RecordMapper;
+use SocialDept\AtpParity\Signals\ParitySignal;
+use SocialDept\AtpSignals\Events\SignalEvent;
+
+class CustomParitySignal extends ParitySignal
+{
+    protected function handleUpsert(SignalEvent $event, RecordMapper $mapper): void
+    {
+        // Pre-processing
+        logger()->info('Syncing record', [
+            'did' => $event->did,
+            'collection' => $event->commit->collection,
+            'rkey' => $event->commit->rkey,
+        ]);
+
+        // Call parent to do the actual sync
+        parent::handleUpsert($event, $mapper);
+
+        // Post-processing
+        // e.g., dispatch a job, send notification, etc.
+    }
+
+    protected function handleDelete(SignalEvent $event, RecordMapper $mapper): void
+    {
+        logger()->info('Deleting record', [
+            'uri' => $this->buildUri($event->did, $event->commit->collection, $event->commit->rkey),
+        ]);
+
+        parent::handleDelete($event, $mapper);
+    }
+}
+```
+
+## Queue Integration
+
+For high-volume processing, enable queue mode:
+
+```php
+namespace App\Signals;
+
+use SocialDept\AtpParity\Signals\ParitySignal;
+
+class QueuedParitySignal extends ParitySignal
+{
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function queue(): string
+    {
+        return 'parity-sync';
+    }
+}
+```
+
+Then run a dedicated queue worker:
+
+```bash
+php artisan queue:work --queue=parity-sync
+```
+
+## Multiple Signals
+
+You can run ParitySignal alongside other signals:
+
+```php
+// config/signal.php
+return [
+    'signals' => [
+        // Sync to database
+        \SocialDept\AtpParity\Signals\ParitySignal::class,
+
+        // Your custom analytics signal
+        App\Signals\AnalyticsSignal::class,
+
+        // Your moderation signal
+        App\Signals\ModerationSignal::class,
+    ],
+];
+```
+
+## Handling High Volume
+
+The AT Protocol firehose processes thousands of events per second. For production:
+
+### 1. Use Jetstream Mode
+
+Jetstream filters server-side, reducing bandwidth:
+
+```php
+// config/signal.php
+return [
+    'mode' => 'jetstream', // More efficient than firehose
+
+    'jetstream' => [
+        'collections' => [
+            'app.bsky.feed.post',
+            'app.bsky.feed.like',
+        ],
+    ],
+];
+```
+
+### 2. Enable Queues
+
+Process events asynchronously:
+
+```php
+class QueuedParitySignal extends ParitySignal
+{
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+}
+```
+
+### 3. Use Database Transactions
+
+Batch inserts for better performance:
+
+```php
+namespace App\Signals;
+
+use Illuminate\Support\Facades\DB;
+use SocialDept\AtpParity\Signals\ParitySignal;
+use SocialDept\AtpSignals\Events\SignalEvent;
+
+class BatchedParitySignal extends ParitySignal
+{
+    protected array $buffer = [];
+    protected int $batchSize = 100;
+
+    public function handle(SignalEvent $event): void
+    {
+        $this->buffer[] = $event;
+
+        if (count($this->buffer) >= $this->batchSize) {
+            $this->flush();
+        }
+    }
+
+    protected function flush(): void
+    {
+        DB::transaction(function () {
+            foreach ($this->buffer as $event) {
+                parent::handle($event);
+            }
+        });
+
+        $this->buffer = [];
+    }
+}
+```
+
+### 4. Monitor Performance
+
+Log sync statistics:
+
+```php
+namespace App\Signals;
+
+use SocialDept\AtpParity\Signals\ParitySignal;
+use SocialDept\AtpSignals\Events\SignalEvent;
+
+class MonitoredParitySignal extends ParitySignal
+{
+    protected int $processed = 0;
+    protected float $startTime;
+
+    public function handle(SignalEvent $event): void
+    {
+        $this->startTime ??= microtime(true);
+
+        parent::handle($event);
+
+        $this->processed++;
+
+        if ($this->processed % 1000 === 0) {
+            $elapsed = microtime(true) - $this->startTime;
+            $rate = $this->processed / $elapsed;
+
+            logger()->info("Parity sync stats", [
+                'processed' => $this->processed,
+                'elapsed' => round($elapsed, 2),
+                'rate' => round($rate, 2) . '/sec',
+            ]);
+        }
+    }
+}
+```
+
+## Cursor Management
+
+atp-signals handles cursor persistence automatically. If the consumer restarts, it resumes from where it left off.
+
+To reset and start fresh:
+
+```bash
+php artisan signal:consume --reset
+```
+
+## Testing
+
+Test your sync setup without connecting to the firehose:
+
+```php
+use App\AtpMappers\PostMapper;
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post;
+
+// Create a test record
+$record = Post::fromArray([
+    'text' => 'Test post content',
+    'createdAt' => now()->toIso8601String(),
+]);
+
+// Get the mapper
+$registry = app(MapperRegistry::class);
+$mapper = $registry->forLexicon('app.bsky.feed.post');
+
+// Simulate a sync
+$model = $mapper->upsert($record, [
+    'uri' => 'at://did:plc:test/app.bsky.feed.post/test123',
+    'cid' => 'bafyretest...',
+]);
+
+// Assert
+$this->assertDatabaseHas('posts', [
+    'content' => 'Test post content',
+    'atp_uri' => 'at://did:plc:test/app.bsky.feed.post/test123',
+]);
+```

docs/importing.md

···
+# Importing Records
+
+Parity includes a comprehensive import system that enables you to sync historical AT Protocol data to your Eloquent models. This complements the real-time sync provided by [ParitySignal](atp-signals-integration.md).
+
+## The Cold Start Problem
+
+When you start consuming the AT Protocol firehose with ParitySignal, you only receive events from that point forward. Any records created before you started listening are not captured.
+
+Importing solves this "cold start" problem by fetching existing records from user repositories via the `com.atproto.repo.listRecords` API.
+
+## Quick Start
+
+### 1. Run the Migration
+
+Publish and run the migration to create the import state tracking table:
+
+```bash
+php artisan vendor:publish --tag=parity-migrations
+php artisan migrate
+```
+
+### 2. Import a User
+
+```bash
+# Import all registered collections for a user
+php artisan parity:import did:plc:z72i7hdynmk6r22z27h6tvur
+
+# Import a specific collection
+php artisan parity:import did:plc:z72i7hdynmk6r22z27h6tvur --collection=app.bsky.feed.post
+
+# Show progress
+php artisan parity:import did:plc:z72i7hdynmk6r22z27h6tvur --progress
+```
+
+### 3. Check Status
+
+```bash
+# Show all import status
+php artisan parity:import-status
+
+# Show status for a specific user
+php artisan parity:import-status did:plc:z72i7hdynmk6r22z27h6tvur
+
+# Show only incomplete imports
+php artisan parity:import-status --pending
+```
+
+## Programmatic Usage
+
+### ImportService
+
+The `ImportService` is the main orchestration class:
+
+```php
+use SocialDept\AtpParity\Import\ImportService;
+
+$service = app(ImportService::class);
+
+// Import all registered collections for a user
+$result = $service->importUser('did:plc:z72i7hdynmk6r22z27h6tvur');
+
+echo "Synced {$result->recordsSynced} records";
+
+// Import a specific collection
+$result = $service->importUserCollection(
+    'did:plc:z72i7hdynmk6r22z27h6tvur',
+    'app.bsky.feed.post'
+);
+
+// With progress callback
+$result = $service->importUser('did:plc:z72i7hdynmk6r22z27h6tvur', null, function ($progress) {
+    echo "Synced {$progress->recordsSynced} records from {$progress->collection}\n";
+});
+```
+
+### ImportResult
+
+The `ImportResult` value object provides information about the import operation:
+
+```php
+$result = $service->importUser($did);
+
+$result->recordsSynced;   // Number of records successfully synced
+$result->recordsSkipped;  // Number of records skipped
+$result->recordsFailed;   // Number of records that failed to sync
+$result->completed;       // Whether the import completed fully
+$result->cursor;          // Cursor for resuming (if incomplete)
+$result->error;           // Error message (if failed)
+
+$result->isSuccess();     // True if completed without errors
+$result->isPartial();     // True if some records were synced before failure
+$result->isFailed();      // True if an error occurred
+```
+
+### Checking Status
+
+```php
+// Check if a collection has been imported
+if ($service->isImported($did, 'app.bsky.feed.post')) {
+    echo "Already imported!";
+}
+
+// Get detailed status
+$state = $service->getStatus($did, 'app.bsky.feed.post');
+
+if ($state) {
+    echo "Status: {$state->status}";
+    echo "Records synced: {$state->records_synced}";
+}
+
+// Get all statuses for a user
+$states = $service->getStatusForUser($did);
+```
+
+### Resuming Interrupted Imports
+
+If an import is interrupted (network error, timeout, etc.), you can resume it:
+
+```php
+// Resume a specific import
+$state = $service->getStatus($did, $collection);
+if ($state && $state->canResume()) {
+    $result = $service->resume($state);
+}
+
+// Resume all interrupted imports
+$results = $service->resumeAll();
+```
+
+### Resetting Import State
+
+To re-import a user or collection:
+
+```php
+// Reset a specific collection
+$service->reset($did, 'app.bsky.feed.post');
+
+// Reset all collections for a user
+$service->resetUser($did);
+```
+
+## Queue Integration
+
+For large-scale importing, use the queue system:
+
+### Command Line
+
+```bash
+# Queue an import job instead of running synchronously
+php artisan parity:import did:plc:z72i7hdynmk6r22z27h6tvur --queue
+
+# Queue imports for a list of DIDs
+php artisan parity:import --file=dids.txt --queue
+```
+
+### Programmatic
+
+```php
+use SocialDept\AtpParity\Jobs\ImportUserJob;
+
+// Dispatch a single user import
+ImportUserJob::dispatch('did:plc:z72i7hdynmk6r22z27h6tvur');
+
+// Dispatch for a specific collection
+ImportUserJob::dispatch('did:plc:z72i7hdynmk6r22z27h6tvur', 'app.bsky.feed.post');
+```
+
+## Events
+
+Parity dispatches events during importing that you can listen to:
+
+### ImportStarted
+
+Fired when an import operation begins:
+
+```php
+use SocialDept\AtpParity\Events\ImportStarted;
+
+Event::listen(ImportStarted::class, function (ImportStarted $event) {
+    Log::info("Starting import", [
+        'did' => $event->did,
+        'collection' => $event->collection,
+    ]);
+});
+```
+
+### ImportProgress
+
+Fired after each page of records is processed:
+
+```php
+use SocialDept\AtpParity\Events\ImportProgress;
+
+Event::listen(ImportProgress::class, function (ImportProgress $event) {
+    Log::info("Import progress", [
+        'did' => $event->did,
+        'collection' => $event->collection,
+        'records_synced' => $event->recordsSynced,
+    ]);
+});
+```
+
+### ImportCompleted
+
+Fired when an import operation completes successfully:
+
+```php
+use SocialDept\AtpParity\Events\ImportCompleted;
+
+Event::listen(ImportCompleted::class, function (ImportCompleted $event) {
+    $result = $event->result;
+
+    Log::info("Import completed", [
+        'did' => $result->did,
+        'collection' => $result->collection,
+        'records_synced' => $result->recordsSynced,
+    ]);
+});
+```
+
+### ImportFailed
+
+Fired when an import operation fails:
+
+```php
+use SocialDept\AtpParity\Events\ImportFailed;
+
+Event::listen(ImportFailed::class, function (ImportFailed $event) {
+    Log::error("Import failed", [
+        'did' => $event->did,
+        'collection' => $event->collection,
+        'error' => $event->error,
+    ]);
+});
+```
+
+## Configuration
+
+Configure importing in `config/parity.php`:
+
+```php
+'import' => [
+    // Records per page when listing from PDS (max 100)
+    'page_size' => 100,
+
+    // Delay between pages in milliseconds (rate limiting)
+    'page_delay' => 100,
+
+    // Queue name for import jobs
+    'queue' => 'parity-import',
+
+    // Database table for storing import state
+    'state_table' => 'parity_import_states',
+],
+```
+
+## Batch Importing from File
+
+Create a file with DIDs (one per line):
+
+```text
+did:plc:z72i7hdynmk6r22z27h6tvur
+did:plc:ewvi7nxzyoun6zhxrhs64oiz
+did:plc:ragtjsm2j2vknwkz3zp4oxrd
+```
+
+Then run:
+
+```bash
+# Synchronous (one at a time)
+php artisan parity:import --file=dids.txt --progress
+
+# Queued (parallel via workers)
+php artisan parity:import --file=dids.txt --queue
+```
+
+## Coordinating with ParitySignal
+
+For a complete sync solution, combine importing with real-time firehose sync:
+
+1. **Start the firehose consumer** - Begin receiving live events
+2. **Import historical data** - Fetch existing records
+3. **Continue firehose sync** - New events are handled automatically
+
+This ensures no gaps in your data. Records that arrive via firehose while importing will be properly deduplicated by the mapper's `upsert()` method (which uses the AT Protocol URI as the unique key).
+
+```php
+// Example: Import a user then subscribe to their updates
+$service->importUser($did);
+
+// The firehose consumer (ParitySignal) handles updates automatically
+// as long as it's running with signal:consume
+```
+
+## Best Practices
+
+### Rate Limiting
+
+The `page_delay` config option helps prevent overwhelming PDS servers. For bulk importing, consider:
+
+- Using queued jobs to spread load over time
+- Increasing the delay between pages
+- Running during off-peak hours
+
+### Error Handling
+
+Imports can fail due to:
+- Network errors
+- PDS rate limiting
+- Invalid records
+
+The system automatically tracks progress via cursor, allowing you to resume failed imports:
+
+```bash
+# Check for failed imports
+php artisan parity:import-status --failed
+
+# Resume all failed/interrupted imports
+php artisan parity:import --resume
+```
+
+### Monitoring
+
+Use the events to build monitoring:
+
+```php
+// Track import metrics
+Event::listen(ImportCompleted::class, function (ImportCompleted $event) {
+    Metrics::increment('parity.import.completed');
+    Metrics::gauge('parity.import.records', $event->result->recordsSynced);
+});
+
+Event::listen(ImportFailed::class, function (ImportFailed $event) {
+    Metrics::increment('parity.import.failed');
+    Alert::send("Import failed for {$event->did}: {$event->error}");
+});
+```
+
+## Database Schema
+
+The import state table stores progress:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | bigint | Primary key |
+| did | string | The DID being imported |
+| collection | string | The collection NSID |
+| status | string | pending, in_progress, completed, failed |
+| cursor | string | Pagination cursor for resuming |
+| records_synced | int | Count of successfully synced records |
+| records_skipped | int | Count of skipped records |
+| records_failed | int | Count of failed records |
+| started_at | timestamp | When import started |
+| completed_at | timestamp | When import completed |
+| error | text | Error message if failed |
+| created_at | timestamp | |
+| updated_at | timestamp | |
+
+The combination of `did` and `collection` is unique.

docs/mappers.md

···
+# Record Mappers
+
+Mappers are the core of atp-parity. They define bidirectional transformations between AT Protocol record DTOs and Eloquent models.
+
+## Creating a Mapper
+
+Extend the `RecordMapper` abstract class and implement the required methods:
+
+```php
+<?php
+
+namespace App\AtpMappers;
+
+use App\Models\Post;
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\RecordMapper;
+use SocialDept\AtpSchema\Data\Data;
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post as PostRecord;
+
+/**
+ * @extends RecordMapper<PostRecord, Post>
+ */
+class PostMapper extends RecordMapper
+{
+    /**
+     * The AT Protocol record class this mapper handles.
+     */
+    public function recordClass(): string
+    {
+        return PostRecord::class;
+    }
+
+    /**
+     * The Eloquent model class this mapper handles.
+     */
+    public function modelClass(): string
+    {
+        return Post::class;
+    }
+
+    /**
+     * Transform a record DTO into model attributes.
+     */
+    protected function recordToAttributes(Data $record): array
+    {
+        /** @var PostRecord $record */
+        return [
+            'content' => $record->text,
+            'published_at' => $record->createdAt,
+            'langs' => $record->langs,
+            'facets' => $record->facets,
+        ];
+    }
+
+    /**
+     * Transform a model into record data for creating/updating.
+     */
+    protected function modelToRecordData(Model $model): array
+    {
+        /** @var Post $model */
+        return [
+            'text' => $model->content,
+            'createdAt' => $model->published_at->toIso8601String(),
+            'langs' => $model->langs ?? ['en'],
+        ];
+    }
+}
+```
+
+## Required Methods
+
+### `recordClass(): string`
+
+Returns the fully qualified class name of the AT Protocol record DTO. This can be:
+
+- A generated class from atp-schema (e.g., `SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post`)
+- A custom class extending `SocialDept\AtpParity\Data\Record`
+
+### `modelClass(): string`
+
+Returns the fully qualified class name of the Eloquent model.
+
+### `recordToAttributes(Data $record): array`
+
+Transforms an AT Protocol record into an array of Eloquent model attributes. This is used when:
+
+- Creating a new model from a remote record
+- Updating an existing model from a remote record
+
+### `modelToRecordData(Model $model): array`
+
+Transforms an Eloquent model into an array suitable for creating an AT Protocol record. This is used when:
+
+- Publishing a local model to the AT Protocol network
+- Comparing local and remote state
+
+## Inherited Methods
+
+The abstract `RecordMapper` class provides these methods:
+
+### `lexicon(): string`
+
+Returns the lexicon NSID (e.g., `app.bsky.feed.post`). Automatically derived from the record class's `getLexicon()` method.
+
+### `toModel(Data $record, array $meta = []): Model`
+
+Creates a new (unsaved) model instance from a record DTO.
+
+```php
+$record = PostRecord::fromArray($data);
+$model = $mapper->toModel($record, [
+    'uri' => 'at://did:plc:xxx/app.bsky.feed.post/abc123',
+    'cid' => 'bafyre...',
+]);
+```
+
+### `toRecord(Model $model): Data`
+
+Converts a model back to a record DTO.
+
+```php
+$record = $mapper->toRecord($post);
+// Use $record->toArray() to get data for API calls
+```
+
+### `updateModel(Model $model, Data $record, array $meta = []): Model`
+
+Updates an existing model with data from a record. Does not save the model.
+
+```php
+$mapper->updateModel($existingPost, $record, ['cid' => $newCid]);
+$existingPost->save();
+```
+
+### `findByUri(string $uri): ?Model`
+
+Finds a model by its AT Protocol URI.
+
+```php
+$post = $mapper->findByUri('at://did:plc:xxx/app.bsky.feed.post/abc123');
+```
+
+### `upsert(Data $record, array $meta = []): Model`
+
+Creates or updates a model based on the URI. This is the primary method used for syncing.
+
+```php
+$post = $mapper->upsert($record, [
+    'uri' => $uri,
+    'cid' => $cid,
+]);
+```
+
+### `deleteByUri(string $uri): bool`
+
+Deletes a model by its AT Protocol URI.
+
+```php
+$deleted = $mapper->deleteByUri('at://did:plc:xxx/app.bsky.feed.post/abc123');
+```
+
+## Meta Fields
+
+The `$meta` array passed to `toModel`, `updateModel`, and `upsert` can contain:
+
+| Key | Description |
+|-----|-------------|
+| `uri` | The AT Protocol URI (e.g., `at://did:plc:xxx/app.bsky.feed.post/abc123`) |
+| `cid` | The content identifier hash |
+
+These are automatically mapped to your configured column names (default: `atp_uri`, `atp_cid`).
+
+## Customizing Column Names
+
+Override the column methods to use different database columns:
+
+```php
+class PostMapper extends RecordMapper
+{
+    protected function uriColumn(): string
+    {
+        return 'at_uri'; // Instead of default 'atp_uri'
+    }
+
+    protected function cidColumn(): string
+    {
+        return 'at_cid'; // Instead of default 'atp_cid'
+    }
+
+    // ... other methods
+}
+```
+
+Or configure globally in `config/parity.php`:
+
+```php
+'columns' => [
+    'uri' => 'at_uri',
+    'cid' => 'at_cid',
+],
+```
+
+## Registering Mappers
+
+### Via Configuration
+
+Add your mapper classes to `config/parity.php`:
+
+```php
+return [
+    'mappers' => [
+        App\AtpMappers\PostMapper::class,
+        App\AtpMappers\ProfileMapper::class,
+        App\AtpMappers\LikeMapper::class,
+    ],
+];
+```
+
+### Programmatically
+
+Register mappers at runtime via the `MapperRegistry`:
+
+```php
+use SocialDept\AtpParity\MapperRegistry;
+
+$registry = app(MapperRegistry::class);
+$registry->register(new PostMapper());
+```
+
+## Using the Registry
+
+The `MapperRegistry` provides lookup methods:
+
+```php
+use SocialDept\AtpParity\MapperRegistry;
+
+$registry = app(MapperRegistry::class);
+
+// Find mapper by record class
+$mapper = $registry->forRecord(PostRecord::class);
+
+// Find mapper by model class
+$mapper = $registry->forModel(Post::class);
+
+// Find mapper by lexicon NSID
+$mapper = $registry->forLexicon('app.bsky.feed.post');
+
+// Get all registered lexicons
+$lexicons = $registry->lexicons();
+// ['app.bsky.feed.post', 'app.bsky.actor.profile', ...]
+```
+
+## SchemaMapper for Quick Setup
+
+For simple mappings, use `SchemaMapper` instead of creating a full class:
+
+```php
+use SocialDept\AtpParity\Support\SchemaMapper;
+use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Like;
+
+$mapper = new SchemaMapper(
+    schemaClass: Like::class,
+    modelClass: \App\Models\Like::class,
+    toAttributes: fn(Like $like) => [
+        'subject_uri' => $like->subject->uri,
+        'subject_cid' => $like->subject->cid,
+        'liked_at' => $like->createdAt,
+    ],
+    toRecordData: fn($model) => [
+        'subject' => [
+            'uri' => $model->subject_uri,
+            'cid' => $model->subject_cid,
+        ],
+        'createdAt' => $model->liked_at->toIso8601String(),
+    ],
+);
+
+$registry->register($mapper);
+```
+
+## Handling Complex Records
+
+### Embedded Objects
+
+AT Protocol records often contain embedded objects. Handle them in your mapping:
+
+```php
+protected function recordToAttributes(Data $record): array
+{
+    /** @var PostRecord $record */
+    $attributes = [
+        'content' => $record->text,
+        'published_at' => $record->createdAt,
+    ];
+
+    // Handle reply reference
+    if ($record->reply) {
+        $attributes['reply_to_uri'] = $record->reply->parent->uri;
+        $attributes['thread_root_uri'] = $record->reply->root->uri;
+    }
+
+    // Handle embed
+    if ($record->embed) {
+        $attributes['embed_type'] = $record->embed->getType();
+        $attributes['embed_data'] = $record->embed->toArray();
+    }
+
+    return $attributes;
+}
+```
+
+### Facets (Rich Text)
+
+Posts with mentions, links, and hashtags have facets:
+
+```php
+protected function recordToAttributes(Data $record): array
+{
+    /** @var PostRecord $record */
+    return [
+        'content' => $record->text,
+        'facets' => $record->facets, // Store as JSON
+        'published_at' => $record->createdAt,
+    ];
+}
+
+protected function modelToRecordData(Model $model): array
+{
+    /** @var Post $model */
+    return [
+        'text' => $model->content,
+        'facets' => $model->facets, // Restore from JSON
+        'createdAt' => $model->published_at->toIso8601String(),
+    ];
+}
+```
+
+## Multiple Mappers per Lexicon
+
+You can register multiple mappers for different model types:
+
+```php
+// Map posts to different models based on criteria
+class UserPostMapper extends RecordMapper
+{
+    public function recordClass(): string
+    {
+        return PostRecord::class;
+    }
+
+    public function modelClass(): string
+    {
+        return UserPost::class;
+    }
+
+    // ... mapping logic for user's own posts
+}
+
+class FeedPostMapper extends RecordMapper
+{
+    public function recordClass(): string
+    {
+        return PostRecord::class;
+    }
+
+    public function modelClass(): string
+    {
+        return FeedPost::class;
+    }
+
+    // ... mapping logic for feed posts
+}
+```
+
+Note: The registry will return the first registered mapper for a given lexicon. Use explicit mapper instances when you need specific behavior.

docs/traits.md

···
+# Model Traits
+
+Parity provides two traits to add AT Protocol awareness to your Eloquent models.
+
+## HasAtpRecord
+
+The base trait for models that store AT Protocol record references.
+
+### Setup
+
+```php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\Concerns\HasAtpRecord;
+
+class Post extends Model
+{
+    use HasAtpRecord;
+
+    protected $fillable = [
+        'content',
+        'published_at',
+        'atp_uri',
+        'atp_cid',
+    ];
+}
+```
+
+### Database Migration
+
+```php
+Schema::create('posts', function (Blueprint $table) {
+    $table->id();
+    $table->text('content');
+    $table->timestamp('published_at');
+    $table->string('atp_uri')->nullable()->unique();
+    $table->string('atp_cid')->nullable();
+    $table->timestamps();
+});
+```
+
+### Available Methods
+
+#### `getAtpUri(): ?string`
+
+Returns the stored AT Protocol URI.
+
+```php
+$post->getAtpUri();
+// "at://did:plc:abc123/app.bsky.feed.post/xyz789"
+```
+
+#### `getAtpCid(): ?string`
+
+Returns the stored content identifier.
+
+```php
+$post->getAtpCid();
+// "bafyreib2rxk3rjnlvzj..."
+```
+
+#### `getAtpDid(): ?string`
+
+Extracts the DID from the URI.
+
+```php
+$post->getAtpDid();
+// "did:plc:abc123"
+```
+
+#### `getAtpCollection(): ?string`
+
+Extracts the collection (lexicon NSID) from the URI.
+
+```php
+$post->getAtpCollection();
+// "app.bsky.feed.post"
+```
+
+#### `getAtpRkey(): ?string`
+
+Extracts the record key from the URI.
+
+```php
+$post->getAtpRkey();
+// "xyz789"
+```
+
+#### `hasAtpRecord(): bool`
+
+Checks if the model has been synced to AT Protocol.
+
+```php
+if ($post->hasAtpRecord()) {
+    // Model exists on AT Protocol
+}
+```
+
+#### `getAtpMapper(): ?RecordMapper`
+
+Gets the registered mapper for this model class.
+
+```php
+$mapper = $post->getAtpMapper();
+```
+
+#### `toAtpRecord(): ?Data`
+
+Converts the model to an AT Protocol record DTO.
+
+```php
+$record = $post->toAtpRecord();
+$data = $record->toArray(); // Ready for API calls
+```
+
+### Query Scopes
+
+#### `scopeWithAtpRecord($query)`
+
+Query only models that have been synced.
+
+```php
+$syncedPosts = Post::withAtpRecord()->get();
+```
+
+#### `scopeWithoutAtpRecord($query)`
+
+Query only models that have NOT been synced.
+
+```php
+$localOnlyPosts = Post::withoutAtpRecord()->get();
+```
+
+#### `scopeWhereAtpUri($query, string $uri)`
+
+Find a model by its AT Protocol URI.
+
+```php
+$post = Post::whereAtpUri('at://did:plc:xxx/app.bsky.feed.post/abc')->first();
+```
+
+## SyncsWithAtp
+
+Extended trait for bidirectional synchronization tracking. Includes all `HasAtpRecord` functionality plus sync timestamps and conflict detection.
+
+### Setup
+
+```php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\Concerns\SyncsWithAtp;
+
+class Post extends Model
+{
+    use SyncsWithAtp;
+
+    protected $fillable = [
+        'content',
+        'published_at',
+        'atp_uri',
+        'atp_cid',
+        'atp_synced_at',
+    ];
+
+    protected $casts = [
+        'published_at' => 'datetime',
+        'atp_synced_at' => 'datetime',
+    ];
+}
+```
+
+### Database Migration
+
+```php
+Schema::create('posts', function (Blueprint $table) {
+    $table->id();
+    $table->text('content');
+    $table->timestamp('published_at');
+    $table->string('atp_uri')->nullable()->unique();
+    $table->string('atp_cid')->nullable();
+    $table->timestamp('atp_synced_at')->nullable();
+    $table->timestamps();
+});
+```
+
+### Additional Methods
+
+#### `getAtpSyncedAtColumn(): string`
+
+Returns the column name for the sync timestamp. Override to customize.
+
+```php
+public function getAtpSyncedAtColumn(): string
+{
+    return 'last_synced_at'; // Default: 'atp_synced_at'
+}
+```
+
+#### `getAtpSyncedAt(): ?DateTimeInterface`
+
+Returns when the model was last synced.
+
+```php
+$syncedAt = $post->getAtpSyncedAt();
+// Carbon instance or null
+```
+
+#### `markAsSynced(string $uri, string $cid): void`
+
+Marks the model as synced with the given metadata. Does not save.
+
+```php
+$post->markAsSynced($uri, $cid);
+$post->save();
+```
+
+#### `hasLocalChanges(): bool`
+
+Checks if the model has been modified since the last sync.
+
+```php
+if ($post->hasLocalChanges()) {
+    // Local changes exist that haven't been pushed
+}
+```
+
+This compares `updated_at` with `atp_synced_at`.
+
+#### `updateFromRecord(Data $record, string $uri, string $cid): void`
+
+Updates the model from a remote record. Does not save.
+
+```php
+$post->updateFromRecord($record, $uri, $cid);
+$post->save();
+```
+
+## Practical Examples
+
+### Checking Sync Status
+
+```php
+$post = Post::find(1);
+
+if (!$post->hasAtpRecord()) {
+    echo "Not yet published to AT Protocol";
+} elseif ($post->hasLocalChanges()) {
+    echo "Has unpushed local changes";
+} else {
+    echo "In sync with AT Protocol";
+}
+```
+
+### Finding Related Records
+
+```php
+// Get all posts from the same author
+$authorDid = $post->getAtpDid();
+$authorPosts = Post::withAtpRecord()
+    ->get()
+    ->filter(fn($p) => $p->getAtpDid() === $authorDid);
+```
+
+### Building an AT Protocol URL
+
+```php
+$post = Post::find(1);
+
+if ($post->hasAtpRecord()) {
+    $bskyUrl = sprintf(
+        'https://bsky.app/profile/%s/post/%s',
+        $post->getAtpDid(),
+        $post->getAtpRkey()
+    );
+}
+```
+
+### Sync Status Dashboard
+
+```php
+// Get sync statistics
+$stats = [
+    'total' => Post::count(),
+    'synced' => Post::withAtpRecord()->count(),
+    'pending' => Post::withoutAtpRecord()->count(),
+    'with_changes' => Post::withAtpRecord()
+        ->get()
+        ->filter(fn($p) => $p->hasLocalChanges())
+        ->count(),
+];
+```
+
+## Custom Column Names
+
+Both traits respect the global column configuration:
+
+```php
+// config/parity.php
+return [
+    'columns' => [
+        'uri' => 'at_protocol_uri',
+        'cid' => 'at_protocol_cid',
+    ],
+];
+```
+
+For the sync timestamp column, override the method in your model:
+
+```php
+class Post extends Model
+{
+    use SyncsWithAtp;
+
+    public function getAtpSyncedAtColumn(): string
+    {
+        return 'last_synced_at';
+    }
+}
+```
+
+## Event Hooks
+
+The `SyncsWithAtp` trait includes a boot method you can extend:
+
+```php
+class Post extends Model
+{
+    use SyncsWithAtp;
+
+    protected static function bootSyncsWithAtp(): void
+    {
+        parent::bootSyncsWithAtp();
+
+        static::updating(function ($model) {
+            // Custom logic before updates
+        });
+    }
+}
+```
+
+## Combining with Other Traits
+
+The traits work alongside other Eloquent features:
+
+```php
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use SocialDept\AtpParity\Concerns\SyncsWithAtp;
+
+class Post extends Model
+{
+    use SoftDeletes;
+    use SyncsWithAtp;
+
+    // Both traits work together
+}
+```

license.md

···
-# The license
-
-Copyright (c) Author Name <[e-mail]>
-
-...Add your license text here...

phpunit.xml

···
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit bootstrap="vendor/autoload.php"
-         backupGlobals="false"
-         backupStaticAttributes="false"
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
          colors="true"
-         verbose="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false">
+         cacheDirectory=".phpunit.cache">
     <testsuites>
-        <testsuite name="Package">
-            <directory suffix=".php">./tests/</directory>
+        <testsuite name="Parity Test Suite">
+            <directory suffix="Test.php">./tests/</directory>
+            <exclude>./tests/Fixtures/</exclude>
         </testsuite>
     </testsuites>
-    <filter>
-        <whitelist>
+    <source>
+        <include>
             <directory>src/</directory>
-        </whitelist>
-    </filter>
+        </include>
+    </source>
+    <php>
+        <env name="APP_ENV" value="testing"/>
+        <env name="CACHE_DRIVER" value="array"/>
+        <env name="SESSION_DRIVER" value="array"/>
+        <env name="QUEUE_CONNECTION" value="sync"/>
+        <env name="DB_CONNECTION" value="sqlite"/>
+        <env name="DB_DATABASE" value=":memory:"/>
+    </php>
 </phpunit>

readme.md

···
-# AtpReplicator
-
-[![Latest Version on Packagist][ico-version]][link-packagist]
-[![Total Downloads][ico-downloads]][link-downloads]
-[![Build Status][ico-travis]][link-travis]
-[![StyleCI][ico-styleci]][link-styleci]
-
-This is where your description should go. Take a look at [contributing.md](contributing.md) to see a to do list.
-
-## Installation
-
-Via Composer
-
-```bash
-composer require socialdept/atp-parity
-```
-
-## Usage
-
-## Change log
-
-Please see the [changelog](changelog.md) for more information on what has changed recently.
-
-## Testing
-
-```bash
-composer test
-```
-
-## Contributing
-
-Please see [contributing.md](contributing.md) for details and a todolist.
-
-## Security
-
-If you discover any security related issues, please email [e-mail] instead of using the issue tracker.
-
-## Credits
-
-- [Author Name][link-author]
-- [All Contributors][link-contributors]
-
-## License
-
-MIT. Please see the [license file](license.md) for more information.
-
-[ico-version]: https://img.shields.io/packagist/v/socialdept/atp-parity.svg?style=flat-square
-[ico-downloads]: https://img.shields.io/packagist/dt/socialdept/atp-parity.svg?style=flat-square
-[ico-travis]: https://img.shields.io/travis/socialdept/atp-parity/master.svg?style=flat-square
-[ico-styleci]: https://styleci.io/repos/12345678/shield
-
-[link-packagist]: https://packagist.org/packages/socialdept/atp-parity
-[link-downloads]: https://packagist.org/packages/socialdept/atp-parity
-[link-travis]: https://travis-ci.org/socialdept/atp-parity
-[link-styleci]: https://styleci.io/repos/12345678
-[link-author]: https://github.com/social-dept
-[link-contributors]: ../../contributors

src/AtpReplicator.php

···
-<?php
-
-namespace SocialDept\AtpReplicator;
-
-class AtpReplicator
-{
-    // Build wonderful things
-}

src/AtpReplicatorServiceProvider.php

···
-<?php
-
-namespace SocialDept\AtpReplicator;
-
-use Illuminate\Support\ServiceProvider;
-
-class AtpReplicatorServiceProvider extends ServiceProvider
-{
-    /**
-     * Perform post-registration booting of services.
-     *
-     * @return void
-     */
-    public function boot(): void
-    {
-        // $this->loadTranslationsFrom(__DIR__.'/../resources/lang', 'social-dept');
-        // $this->loadViewsFrom(__DIR__.'/../resources/views', 'social-dept');
-        // $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
-        // $this->loadRoutesFrom(__DIR__.'/routes.php');
-
-        // Publishing is only necessary when using the CLI.
-        if ($this->app->runningInConsole()) {
-            $this->bootForConsole();
-        }
-    }
-
-    /**
-     * Register any package services.
-     *
-     * @return void
-     */
-    public function register(): void
-    {
-        $this->mergeConfigFrom(__DIR__.'/../config/atp-replicator.php', 'atp-replicator');
-
-        // Register the service the package provides.
-        $this->app->singleton('atp-replicator', function ($app) {
-            return new AtpReplicator;
-        });
-    }
-
-    /**
-     * Get the services provided by the provider.
-     *
-     * @return array
-     */
-    public function provides()
-    {
-        return ['atp-replicator'];
-    }
-
-    /**
-     * Console-specific booting.
-     *
-     * @return void
-     */
-    protected function bootForConsole(): void
-    {
-        // Publishing the configuration file.
-        $this->publishes([
-            __DIR__.'/../config/atp-replicator.php' => config_path('atp-replicator.php'),
-        ], 'atp-replicator.config');
-
-        // Publishing the views.
-        /*$this->publishes([
-            __DIR__.'/../resources/views' => base_path('resources/views/vendor/social-dept'),
-        ], 'atp-replicator.views');*/
-
-        // Publishing assets.
-        /*$this->publishes([
-            __DIR__.'/../resources/assets' => public_path('vendor/social-dept'),
-        ], 'atp-replicator.assets');*/
-
-        // Publishing the translation files.
-        /*$this->publishes([
-            __DIR__.'/../resources/lang' => resource_path('lang/vendor/social-dept'),
-        ], 'atp-replicator.lang');*/
-
-        // Registering package commands.
-        // $this->commands([]);
-    }
-}

src/Commands/DiscoverCommand.php

···
+<?php
+
+namespace SocialDept\AtpParity\Commands;
+
+use Illuminate\Console\Command;
+use SocialDept\AtpParity\Discovery\DiscoveryService;
+
+use function Laravel\Prompts\error;
+use function Laravel\Prompts\info;
+use function Laravel\Prompts\note;
+
+class DiscoverCommand extends Command
+{
+    protected $signature = 'parity:discover
+        {collection : The collection NSID to discover (e.g., app.bsky.feed.post)}
+        {--limit= : Maximum number of DIDs to discover}
+        {--import : Import records for discovered DIDs}
+        {--output= : Output DIDs to file (one per line)}
+        {--count : Only count DIDs without listing them}';
+
+    protected $description = 'Discover DIDs with records in a specific collection';
+
+    public function handle(DiscoveryService $service): int
+    {
+        $collection = $this->argument('collection');
+        $limit = $this->option('limit') ? (int) $this->option('limit') : null;
+
+        if ($this->option('count')) {
+            return $this->handleCount($service, $collection);
+        }
+
+        if ($this->option('import')) {
+            return $this->handleDiscoverAndImport($service, $collection, $limit);
+        }
+
+        return $this->handleDiscover($service, $collection, $limit);
+    }
+
+    protected function handleCount(DiscoveryService $service, string $collection): int
+    {
+        info("Counting DIDs with records in {$collection}...");
+
+        $count = $service->count($collection);
+
+        info("Found {$count} DIDs");
+
+        return self::SUCCESS;
+    }
+
+    protected function handleDiscover(DiscoveryService $service, string $collection, ?int $limit): int
+    {
+        $limitDisplay = $limit ? " (limit: {$limit})" : '';
+        info("Discovering DIDs with records in {$collection}{$limitDisplay}...");
+
+        $result = $service->discover($collection, $limit);
+
+        if ($result->isFailed()) {
+            error("Discovery failed: {$result->error}");
+
+            return self::FAILURE;
+        }
+
+        if ($result->total === 0) {
+            note('No DIDs found');
+
+            return self::SUCCESS;
+        }
+
+        // Output to file if requested
+        if ($output = $this->option('output')) {
+            file_put_contents($output, implode("\n", $result->dids)."\n");
+            info("Found {$result->total} DIDs, written to {$output}");
+
+            if ($result->isIncomplete()) {
+                note('Results may be incomplete due to limit');
+            }
+
+            return self::SUCCESS;
+        }
+
+        // Output to console
+        foreach ($result->dids as $did) {
+            $this->line($did);
+        }
+
+        info("Found {$result->total} DIDs");
+
+        if ($result->isIncomplete()) {
+            note('Results may be incomplete due to limit');
+        }
+
+        return self::SUCCESS;
+    }
+
+    protected function handleDiscoverAndImport(DiscoveryService $service, string $collection, ?int $limit): int
+    {
+        $limitDisplay = $limit ? " (limit: {$limit})" : '';
+        info("Discovering and importing DIDs with records in {$collection}{$limitDisplay}...");
+
+        $result = $service->discoverAndImport(
+            $collection,
+            $limit,
+            function (string $did, int $count) {
+                note("[{$count}] Importing {$did}");
+            }
+        );
+
+        if ($result->isFailed()) {
+            error("Discovery failed: {$result->error}");
+
+            return self::FAILURE;
+        }
+
+        info("Imported records for {$result->total} DIDs");
+
+        if ($result->isIncomplete()) {
+            note('Results may be incomplete due to limit');
+        }
+
+        return self::SUCCESS;
+    }
+}

src/Commands/ExportCommand.php

···
+<?php
+
+namespace SocialDept\AtpParity\Commands;
+
+use Illuminate\Console\Command;
+use SocialDept\AtpParity\Events\ImportProgress;
+use SocialDept\AtpParity\Export\ExportService;
+
+use function Laravel\Prompts\error;
+use function Laravel\Prompts\info;
+use function Laravel\Prompts\note;
+
+class ExportCommand extends Command
+{
+    protected $signature = 'parity:export
+        {did : The DID to export}
+        {--output= : Output CAR file path}
+        {--import : Import records to database instead of saving CAR file}
+        {--collection=* : Specific collections to import (with --import)}
+        {--since= : Only export changes since this revision}
+        {--status : Show repository status instead of exporting}';
+
+    protected $description = 'Export an AT Protocol repository as CAR file or import to database';
+
+    public function handle(ExportService $service): int
+    {
+        $did = $this->argument('did');
+
+        if (! str_starts_with($did, 'did:')) {
+            error("Invalid DID format: {$did}");
+
+            return self::FAILURE;
+        }
+
+        if ($this->option('status')) {
+            return $this->handleStatus($service, $did);
+        }
+
+        if ($this->option('import')) {
+            return $this->handleImport($service, $did);
+        }
+
+        return $this->handleExport($service, $did);
+    }
+
+    protected function handleStatus(ExportService $service, string $did): int
+    {
+        info("Getting repository status for {$did}...");
+
+        try {
+            $commit = $service->getLatestCommit($did);
+            $status = $service->getRepoStatus($did);
+
+            $this->table(['Property', 'Value'], [
+                ['DID', $did],
+                ['Latest CID', $commit['cid'] ?? 'N/A'],
+                ['Latest Rev', $commit['rev'] ?? 'N/A'],
+                ['Active', ($status['active'] ?? false) ? 'Yes' : 'No'],
+                ['Status', $status['status'] ?? 'N/A'],
+            ]);
+
+            return self::SUCCESS;
+        } catch (\Throwable $e) {
+            error("Failed to get status: {$e->getMessage()}");
+
+            return self::FAILURE;
+        }
+    }
+
+    protected function handleExport(ExportService $service, string $did): int
+    {
+        $output = $this->option('output') ?? "{$did}.car";
+        $since = $this->option('since');
+
+        // Sanitize filename if using DID as filename
+        $output = str_replace([':', '/'], ['_', '_'], $output);
+
+        info("Exporting repository {$did} to {$output}...");
+
+        $result = $service->exportToFile($did, $output, $since);
+
+        if ($result->isFailed()) {
+            error("Export failed: {$result->error}");
+
+            return self::FAILURE;
+        }
+
+        $size = $this->formatBytes($result->size);
+        info("Exported {$size} to {$output}");
+
+        return self::SUCCESS;
+    }
+
+    protected function handleImport(ExportService $service, string $did): int
+    {
+        $collections = $this->option('collection') ?: null;
+        $collectionDisplay = $collections ? implode(', ', $collections) : 'all registered';
+
+        info("Exporting and importing {$did} ({$collectionDisplay})...");
+
+        $result = $service->exportAndImport(
+            $did,
+            $collections,
+            function (ImportProgress $progress) {
+                $this->output->write("\r");
+                $this->output->write("  [{$progress->collection}] {$progress->recordsSynced} records synced");
+            }
+        );
+
+        $this->output->write("\n");
+
+        if ($result->isFailed()) {
+            error("Import failed: {$result->error}");
+
+            return self::FAILURE;
+        }
+
+        info("Imported {$result->size} records");
+
+        return self::SUCCESS;
+    }
+
+    protected function formatBytes(int $bytes): string
+    {
+        $units = ['B', 'KB', 'MB', 'GB'];
+        $unit = 0;
+
+        while ($bytes >= 1024 && $unit < count($units) - 1) {
+            $bytes /= 1024;
+            $unit++;
+        }
+
+        return round($bytes, 2).' '.$units[$unit];
+    }
+}

src/Commands/ImportCommand.php

···
+<?php
+
+namespace SocialDept\AtpParity\Commands;
+
+use Illuminate\Console\Command;
+use SocialDept\AtpParity\Events\ImportProgress;
+use SocialDept\AtpParity\Import\ImportService;
+use SocialDept\AtpParity\Jobs\ImportUserJob;
+use SocialDept\AtpParity\MapperRegistry;
+
+use function Laravel\Prompts\error;
+use function Laravel\Prompts\info;
+use function Laravel\Prompts\note;
+use function Laravel\Prompts\warning;
+
+class ImportCommand extends Command
+{
+    protected $signature = 'parity:import
+        {did? : The DID to import}
+        {--collection= : Specific collection to import}
+        {--file= : File containing DIDs to import (one per line)}
+        {--resume : Resume all interrupted imports}
+        {--queue : Queue the import job instead of running synchronously}
+        {--progress : Show progress output}';
+
+    protected $description = 'Import AT Protocol records for a user or from a file of DIDs';
+
+    public function handle(ImportService $service, MapperRegistry $registry): int
+    {
+        if ($this->option('resume')) {
+            return $this->handleResume($service);
+        }
+
+        $did = $this->argument('did');
+        $file = $this->option('file');
+
+        if (! $did && ! $file) {
+            error('Please provide a DID or use --file to specify a file of DIDs');
+
+            return self::FAILURE;
+        }
+
+        if ($file) {
+            return $this->handleFile($file, $service);
+        }
+
+        return $this->importDid($did, $service, $registry);
+    }
+
+    protected function handleResume(ImportService $service): int
+    {
+        info('Resuming interrupted imports...');
+
+        $results = $service->resumeAll($this->getProgressCallback());
+
+        if (empty($results)) {
+            note('No interrupted imports found');
+
+            return self::SUCCESS;
+        }
+
+        $success = 0;
+        $failed = 0;
+
+        foreach ($results as $result) {
+            if ($result->isSuccess()) {
+                $success++;
+            } else {
+                $failed++;
+            }
+        }
+
+        info("Resumed {$success} imports successfully");
+
+        if ($failed > 0) {
+            warning("{$failed} imports failed");
+        }
+
+        return $failed > 0 ? self::FAILURE : self::SUCCESS;
+    }
+
+    protected function handleFile(string $file, ImportService $service): int
+    {
+        if (! file_exists($file)) {
+            error("File not found: {$file}");
+
+            return self::FAILURE;
+        }
+
+        $dids = array_filter(array_map('trim', file($file)));
+        $total = count($dids);
+        $success = 0;
+        $failed = 0;
+
+        info("Importing {$total} DIDs from {$file}");
+
+        foreach ($dids as $index => $did) {
+            if (! str_starts_with($did, 'did:')) {
+                warning("Skipping invalid DID: {$did}");
+
+                continue;
+            }
+
+            $current = $index + 1;
+            note("[{$current}/{$total}] Importing {$did}");
+
+            if ($this->option('queue')) {
+                ImportUserJob::dispatch($did, $this->option('collection'));
+                $success++;
+            } else {
+                $result = $service->importUser($did, $this->getCollections(), $this->getProgressCallback());
+
+                if ($result->isSuccess()) {
+                    $success++;
+                } else {
+                    $failed++;
+                    warning("Failed: {$result->error}");
+                }
+            }
+        }
+
+        info("Completed: {$success} successful, {$failed} failed");
+
+        return $failed > 0 ? self::FAILURE : self::SUCCESS;
+    }
+
+    protected function importDid(string $did, ImportService $service, MapperRegistry $registry): int
+    {
+        if (! str_starts_with($did, 'did:')) {
+            error("Invalid DID format: {$did}");
+
+            return self::FAILURE;
+        }
+
+        $collections = $this->getCollections();
+        $collectionDisplay = $collections ? implode(', ', $collections) : 'all registered';
+
+        info("Importing {$did} ({$collectionDisplay})");
+
+        if ($this->option('queue')) {
+            ImportUserJob::dispatch($did, $this->option('collection'));
+            note('Import job queued');
+
+            return self::SUCCESS;
+        }
+
+        $result = $service->importUser($did, $collections, $this->getProgressCallback());
+
+        if ($result->isSuccess()) {
+            info("Import completed: {$result->recordsSynced} records synced");
+
+            if ($result->recordsSkipped > 0) {
+                note("{$result->recordsSkipped} records skipped");
+            }
+
+            if ($result->recordsFailed > 0) {
+                warning("{$result->recordsFailed} records failed");
+            }
+
+            return self::SUCCESS;
+        }
+
+        error("Import failed: {$result->error}");
+
+        if ($result->recordsSynced > 0) {
+            note("Partial progress: {$result->recordsSynced} records synced before failure");
+        }
+
+        return self::FAILURE;
+    }
+
+    protected function getCollections(): ?array
+    {
+        $collection = $this->option('collection');
+
+        return $collection ? [$collection] : null;
+    }
+
+    protected function getProgressCallback(): ?callable
+    {
+        if (! $this->option('progress')) {
+            return null;
+        }
+
+        return function (ImportProgress $progress) {
+            $this->output->write("\r");
+            $this->output->write("  [{$progress->collection}] {$progress->recordsSynced} records synced");
+        };
+    }
+}

src/Commands/ImportStatusCommand.php

···
+<?php
+
+namespace SocialDept\AtpParity\Commands;
+
+use Illuminate\Console\Command;
+use SocialDept\AtpParity\Import\ImportState;
+
+use function Laravel\Prompts\info;
+use function Laravel\Prompts\note;
+use function Laravel\Prompts\table;
+use function Laravel\Prompts\warning;
+
+class ImportStatusCommand extends Command
+{
+    protected $signature = 'parity:import-status
+        {did? : Show status for specific DID}
+        {--pending : Show only pending/incomplete imports}
+        {--failed : Show only failed imports}
+        {--completed : Show only completed imports}';
+
+    protected $description = 'Show import status';
+
+    public function handle(): int
+    {
+        $did = $this->argument('did');
+
+        if ($did) {
+            return $this->showDidStatus($did);
+        }
+
+        return $this->showAllStatus();
+    }
+
+    protected function showDidStatus(string $did): int
+    {
+        $states = ImportState::where('did', $did)->get();
+
+        if ($states->isEmpty()) {
+            note("No import records found for {$did}");
+
+            return self::SUCCESS;
+        }
+
+        info("Import status for {$did}");
+
+        table(
+            headers: ['Collection', 'Status', 'Synced', 'Skipped', 'Failed', 'Started', 'Completed'],
+            rows: $states->map(fn (ImportState $state) => [
+                $state->collection,
+                $this->formatStatus($state->status),
+                $state->records_synced,
+                $state->records_skipped,
+                $state->records_failed,
+                $state->started_at?->diffForHumans() ?? '-',
+                $state->completed_at?->diffForHumans() ?? '-',
+            ])->toArray()
+        );
+
+        return self::SUCCESS;
+    }
+
+    protected function showAllStatus(): int
+    {
+        $query = ImportState::query();
+
+        if ($this->option('pending')) {
+            $query->incomplete();
+        } elseif ($this->option('failed')) {
+            $query->failed();
+        } elseif ($this->option('completed')) {
+            $query->completed();
+        }
+
+        $states = $query->orderByDesc('updated_at')->limit(100)->get();
+
+        if ($states->isEmpty()) {
+            note('No import records found');
+
+            return self::SUCCESS;
+        }
+
+        $this->displaySummary();
+
+        table(
+            headers: ['DID', 'Collection', 'Status', 'Synced', 'Updated'],
+            rows: $states->map(fn (ImportState $state) => [
+                $this->truncateDid($state->did),
+                $state->collection,
+                $this->formatStatus($state->status),
+                $state->records_synced,
+                $state->updated_at->diffForHumans(),
+            ])->toArray()
+        );
+
+        if ($states->count() >= 100) {
+            note('Showing first 100 results. Use --pending, --failed, or --completed to filter.');
+        }
+
+        return self::SUCCESS;
+    }
+
+    protected function displaySummary(): void
+    {
+        $counts = ImportState::query()
+            ->selectRaw('status, count(*) as count')
+            ->groupBy('status')
+            ->pluck('count', 'status');
+
+        $pending = $counts->get('pending', 0);
+        $inProgress = $counts->get('in_progress', 0);
+        $completed = $counts->get('completed', 0);
+        $failed = $counts->get('failed', 0);
+
+        info("Import Status Summary");
+        note("Pending: {$pending} | In Progress: {$inProgress} | Completed: {$completed} | Failed: {$failed}");
+
+        if ($failed > 0) {
+            warning("Use 'php artisan parity:import --resume' to retry failed imports");
+        }
+
+        $this->newLine();
+    }
+
+    protected function formatStatus(string $status): string
+    {
+        return match ($status) {
+            ImportState::STATUS_PENDING => 'pending',
+            ImportState::STATUS_IN_PROGRESS => 'running',
+            ImportState::STATUS_COMPLETED => 'done',
+            ImportState::STATUS_FAILED => 'FAILED',
+            default => $status,
+        };
+    }
+
+    protected function truncateDid(string $did): string
+    {
+        if (strlen($did) <= 30) {
+            return $did;
+        }
+
+        return substr($did, 0, 15).'...'.substr($did, -12);
+    }
+}

src/Concerns/AutoPublish.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use SocialDept\AtpParity\Publish\PublishService;
+
+/**
+ * Trait for Eloquent models that automatically publish to AT Protocol.
+ *
+ * This trait sets up model observers to automatically publish, update,
+ * and unpublish records when the model is created, updated, or deleted.
+ *
+ * Override shouldAutoPublish() and shouldAutoUnpublish() to customize
+ * the conditions under which auto-publishing occurs.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait AutoPublish
+{
+    use PublishesRecords;
+
+    /**
+     * Boot the AutoPublish trait.
+     */
+    public static function bootAutoPublish(): void
+    {
+        static::created(function ($model) {
+            if ($model->shouldAutoPublish()) {
+                app(PublishService::class)->publish($model);
+            }
+        });
+
+        static::updated(function ($model) {
+            if ($model->isPublished() && $model->shouldAutoPublish()) {
+                app(PublishService::class)->update($model);
+            }
+        });
+
+        static::deleted(function ($model) {
+            if ($model->isPublished() && $model->shouldAutoUnpublish()) {
+                app(PublishService::class)->delete($model);
+            }
+        });
+    }
+
+    /**
+     * Determine if the model should be auto-published.
+     *
+     * Override this method to add custom conditions.
+     */
+    public function shouldAutoPublish(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine if the model should be auto-unpublished when deleted.
+     *
+     * Override this method to add custom conditions.
+     */
+    public function shouldAutoUnpublish(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the DID to use for auto-publishing.
+     *
+     * Override this method to customize DID resolution.
+     */
+    public function getAutoPublishDid(): ?string
+    {
+        // Check for did column
+        if (isset($this->did)) {
+            return $this->did;
+        }
+
+        // Check for user relationship with did
+        if (method_exists($this, 'user') && $this->user?->did) {
+            return $this->user->did;
+        }
+
+        // Check for author relationship with did
+        if (method_exists($this, 'author') && $this->author?->did) {
+            return $this->author->did;
+        }
+
+        return null;
+    }
+}

src/Concerns/HasAtpRecord.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use SocialDept\AtpParity\Contracts\RecordMapper;
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Trait for Eloquent models that map to AT Protocol records.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait HasAtpRecord
+{
+    /**
+     * Get the AT Protocol URI for this model.
+     */
+    public function getAtpUri(): ?string
+    {
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $this->getAttribute($column);
+    }
+
+    /**
+     * Get the AT Protocol CID for this model.
+     */
+    public function getAtpCid(): ?string
+    {
+        $column = config('parity.columns.cid', 'atp_cid');
+
+        return $this->getAttribute($column);
+    }
+
+    /**
+     * Get the DID from the AT Protocol URI.
+     */
+    public function getAtpDid(): ?string
+    {
+        $uri = $this->getAtpUri();
+
+        if (! $uri) {
+            return null;
+        }
+
+        // at://did:plc:xxx/app.bsky.feed.post/rkey
+        if (preg_match('#^at://([^/]+)/#', $uri, $matches)) {
+            return $matches[1];
+        }
+
+        return null;
+    }
+
+    /**
+     * Get the collection (lexicon NSID) from the AT Protocol URI.
+     */
+    public function getAtpCollection(): ?string
+    {
+        $uri = $this->getAtpUri();
+
+        if (! $uri) {
+            return null;
+        }
+
+        // at://did:plc:xxx/app.bsky.feed.post/rkey
+        if (preg_match('#^at://[^/]+/([^/]+)/#', $uri, $matches)) {
+            return $matches[1];
+        }
+
+        return null;
+    }
+
+    /**
+     * Get the rkey from the AT Protocol URI.
+     */
+    public function getAtpRkey(): ?string
+    {
+        $uri = $this->getAtpUri();
+
+        if (! $uri) {
+            return null;
+        }
+
+        // at://did:plc:xxx/app.bsky.feed.post/rkey
+        if (preg_match('#^at://[^/]+/[^/]+/([^/]+)$#', $uri, $matches)) {
+            return $matches[1];
+        }
+
+        return null;
+    }
+
+    /**
+     * Check if this model has been synced to AT Protocol.
+     */
+    public function hasAtpRecord(): bool
+    {
+        return $this->getAtpUri() !== null;
+    }
+
+    /**
+     * Get the mapper for this model.
+     */
+    public function getAtpMapper(): ?RecordMapper
+    {
+        return app(MapperRegistry::class)->forModel(static::class);
+    }
+
+    /**
+     * Convert this model to an AT Protocol record DTO.
+     */
+    public function toAtpRecord(): ?Data
+    {
+        $mapper = $this->getAtpMapper();
+
+        if (! $mapper) {
+            return null;
+        }
+
+        return $mapper->toRecord($this);
+    }
+
+    /**
+     * Scope to query models that have been synced to AT Protocol.
+     */
+    public function scopeWithAtpRecord($query)
+    {
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $query->whereNotNull($column);
+    }
+
+    /**
+     * Scope to query models that have not been synced to AT Protocol.
+     */
+    public function scopeWithoutAtpRecord($query)
+    {
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $query->whereNull($column);
+    }
+
+    /**
+     * Scope to find by AT Protocol URI.
+     */
+    public function scopeWhereAtpUri($query, string $uri)
+    {
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $query->where($column, $uri);
+    }
+}

src/Concerns/HasAtpRelationships.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * Trait for Eloquent models with AT Protocol relationships.
+ *
+ * Provides helpers for defining relationships based on AT Protocol URI references.
+ * Common relationship patterns:
+ *
+ * - reply.parent -> parent_uri column
+ * - reply.root -> root_uri column
+ * - embed.record (quote) -> quoted_uri column
+ * - like.subject -> subject_uri column
+ * - follow.subject -> subject_did column
+ * - repost.subject -> subject_uri column
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait HasAtpRelationships
+{
+    /**
+     * Define an AT Protocol relationship via URI reference.
+     *
+     * This creates a BelongsTo relationship where the foreign key is an AT Protocol URI
+     * stored in the specified column, matched against the related model's atp_uri column.
+     *
+     * Example:
+     * ```php
+     * public function parent(): BelongsTo
+     * {
+     *     return $this->atpBelongsTo(Post::class, 'parent_uri');
+     * }
+     * ```
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $related
+     */
+    public function atpBelongsTo(string $related, string $uriColumn, ?string $ownerKey = null): BelongsTo
+    {
+        $ownerKey = $ownerKey ?? config('parity.columns.uri', 'atp_uri');
+
+        // Create a custom BelongsTo that uses URI matching
+        return $this->belongsTo($related, $uriColumn, $ownerKey);
+    }
+
+    /**
+     * Define an inverse AT Protocol relationship via URI reference.
+     *
+     * This creates a HasMany relationship where related models have a column
+     * containing this model's AT Protocol URI.
+     *
+     * Example:
+     * ```php
+     * public function replies(): HasMany
+     * {
+     *     return $this->atpHasMany(Post::class, 'parent_uri');
+     * }
+     * ```
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $related
+     */
+    public function atpHasMany(string $related, string $foreignKey, ?string $localKey = null): HasMany
+    {
+        $localKey = $localKey ?? config('parity.columns.uri', 'atp_uri');
+
+        return $this->hasMany($related, $foreignKey, $localKey);
+    }
+
+    /**
+     * Define an AT Protocol relationship via DID reference.
+     *
+     * This creates a BelongsTo relationship where the foreign key is a DID
+     * stored in the specified column, matched against a did column on the related model.
+     *
+     * Example:
+     * ```php
+     * public function subject(): BelongsTo
+     * {
+     *     return $this->atpBelongsToByDid(User::class, 'subject_did');
+     * }
+     * ```
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $related
+     */
+    public function atpBelongsToByDid(string $related, string $didColumn, string $ownerKey = 'did'): BelongsTo
+    {
+        return $this->belongsTo($related, $didColumn, $ownerKey);
+    }
+
+    /**
+     * Define an inverse AT Protocol relationship via DID reference.
+     *
+     * Example:
+     * ```php
+     * public function followers(): HasMany
+     * {
+     *     return $this->atpHasManyByDid(Follow::class, 'subject_did');
+     * }
+     * ```
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $related
+     */
+    public function atpHasManyByDid(string $related, string $foreignKey, string $localKey = 'did'): HasMany
+    {
+        return $this->hasMany($related, $foreignKey, $localKey);
+    }
+
+    /**
+     * Get a related model by AT Protocol URI.
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $modelClass
+     * @return \Illuminate\Database\Eloquent\Model|null
+     */
+    public function findByAtpUri(string $modelClass, ?string $uri)
+    {
+        if (! $uri) {
+            return null;
+        }
+
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $modelClass::where($column, $uri)->first();
+    }
+}

src/Concerns/PublishesRecords.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use SocialDept\AtpParity\Publish\PublishResult;
+use SocialDept\AtpParity\Publish\PublishService;
+
+/**
+ * Trait for Eloquent models that can be manually published to AT Protocol.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait PublishesRecords
+{
+    use HasAtpRecord;
+
+    /**
+     * Publish this model to AT Protocol.
+     *
+     * If the model has a DID association (via did column or relationship),
+     * it will be used. Otherwise, use publishAs() to specify the DID.
+     */
+    public function publish(): PublishResult
+    {
+        return app(PublishService::class)->publish($this);
+    }
+
+    /**
+     * Publish this model as a specific user.
+     */
+    public function publishAs(string $did): PublishResult
+    {
+        return app(PublishService::class)->publishAs($did, $this);
+    }
+
+    /**
+     * Update the published record on AT Protocol.
+     */
+    public function republish(): PublishResult
+    {
+        return app(PublishService::class)->update($this);
+    }
+
+    /**
+     * Delete the record from AT Protocol.
+     */
+    public function unpublish(): bool
+    {
+        return app(PublishService::class)->delete($this);
+    }
+
+    /**
+     * Check if this model has been published to AT Protocol.
+     */
+    public function isPublished(): bool
+    {
+        return $this->hasAtpRecord();
+    }
+}

src/Concerns/SyncsWithAtp.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Trait for models that sync bidirectionally with AT Protocol.
+ *
+ * Extends HasAtpRecord with additional sync tracking and conflict handling.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait SyncsWithAtp
+{
+    use HasAtpRecord;
+
+    /**
+     * Get the column name for tracking the last sync timestamp.
+     */
+    public function getAtpSyncedAtColumn(): string
+    {
+        return 'atp_synced_at';
+    }
+
+    /**
+     * Get the timestamp of the last sync.
+     */
+    public function getAtpSyncedAt(): ?\DateTimeInterface
+    {
+        $column = $this->getAtpSyncedAtColumn();
+
+        return $this->getAttribute($column);
+    }
+
+    /**
+     * Mark the model as synced with the given metadata.
+     */
+    public function markAsSynced(string $uri, string $cid): void
+    {
+        $uriColumn = config('parity.columns.uri', 'atp_uri');
+        $cidColumn = config('parity.columns.cid', 'atp_cid');
+        $syncColumn = $this->getAtpSyncedAtColumn();
+
+        $this->setAttribute($uriColumn, $uri);
+        $this->setAttribute($cidColumn, $cid);
+        $this->setAttribute($syncColumn, now());
+    }
+
+    /**
+     * Check if the model has local changes since last sync.
+     */
+    public function hasLocalChanges(): bool
+    {
+        $syncedAt = $this->getAtpSyncedAt();
+
+        if (! $syncedAt) {
+            return true;
+        }
+
+        $updatedAt = $this->getAttribute('updated_at');
+
+        if (! $updatedAt) {
+            return false;
+        }
+
+        return $updatedAt > $syncedAt;
+    }
+
+    /**
+     * Update the model from a remote record.
+     */
+    public function updateFromRecord(Data $record, string $uri, string $cid): void
+    {
+        $mapper = $this->getAtpMapper();
+
+        if (! $mapper) {
+            return;
+        }
+
+        $mapper->updateModel($this, $record, [
+            'uri' => $uri,
+            'cid' => $cid,
+        ]);
+
+        $this->setAttribute($this->getAtpSyncedAtColumn(), now());
+    }
+
+    /**
+     * Boot the trait.
+     */
+    public static function bootSyncsWithAtp(): void
+    {
+        // Hook into model events if needed
+    }
+}

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/Discovery/DiscoveryResult.php

···
+<?php
+
+namespace SocialDept\AtpParity\Discovery;
+
+/**
+ * Immutable value object representing the result of a discovery operation.
+ */
+readonly class DiscoveryResult
+{
+    public function __construct(
+        public bool $success,
+        public array $dids = [],
+        public int $total = 0,
+        public ?string $error = null,
+        public bool $incomplete = false,
+    ) {}
+
+    /**
+     * Check if the discovery operation succeeded.
+     */
+    public function isSuccess(): bool
+    {
+        return $this->success;
+    }
+
+    /**
+     * Check if the discovery operation failed.
+     */
+    public function isFailed(): bool
+    {
+        return ! $this->success;
+    }
+
+    /**
+     * Check if the discovery was stopped before completion (e.g., limit reached).
+     */
+    public function isIncomplete(): bool
+    {
+        return $this->incomplete;
+    }
+
+    /**
+     * Create a successful result.
+     */
+    public static function success(array $dids, bool $incomplete = false): self
+    {
+        return new self(
+            success: true,
+            dids: $dids,
+            total: count($dids),
+            incomplete: $incomplete,
+        );
+    }
+
+    /**
+     * Create a failed result.
+     */
+    public static function failed(string $error): self
+    {
+        return new self(
+            success: false,
+            error: $error,
+        );
+    }
+}

src/Discovery/DiscoveryService.php

···
+<?php
+
+namespace SocialDept\AtpParity\Discovery;
+
+use BackedEnum;
+use Generator;
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\Import\ImportService;
+use Throwable;
+
+/**
+ * Service for discovering DIDs with records in specific collections.
+ */
+class DiscoveryService
+{
+    public function __construct(
+        protected ImportService $importService
+    ) {}
+
+    /**
+     * Discover all DIDs with records in a collection.
+     *
+     * @return Generator<string> Yields DIDs
+     */
+    public function discoverDids(string|BackedEnum $collection, ?int $limit = null): Generator
+    {
+        $collection = $collection instanceof BackedEnum ? $collection->value : $collection;
+        $cursor = null;
+        $count = 0;
+
+        do {
+            $response = Atp::atproto->sync->listReposByCollection(
+                collection: $collection,
+                limit: min(500, $limit ? $limit - $count : 500),
+                cursor: $cursor,
+            );
+
+            foreach ($response->repos as $repo) {
+                $did = $repo['did'] ?? null;
+
+                if ($did) {
+                    yield $did;
+                    $count++;
+
+                    if ($limit !== null && $count >= $limit) {
+                        return;
+                    }
+                }
+            }
+
+            $cursor = $response->cursor;
+        } while ($cursor !== null);
+    }
+
+    /**
+     * Discover DIDs and return as an array.
+     */
+    public function discover(string|BackedEnum $collection, ?int $limit = null): DiscoveryResult
+    {
+        try {
+            $dids = iterator_to_array($this->discoverDids($collection, $limit));
+            $incomplete = $limit !== null && count($dids) >= $limit;
+
+            return DiscoveryResult::success($dids, $incomplete);
+        } catch (Throwable $e) {
+            return DiscoveryResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * Discover and import all users for a collection.
+     */
+    public function discoverAndImport(
+        string|BackedEnum $collection,
+        ?int $limit = null,
+        ?callable $onProgress = null
+    ): DiscoveryResult {
+        $collection = $collection instanceof BackedEnum ? $collection->value : $collection;
+
+        try {
+            $dids = [];
+            $count = 0;
+
+            foreach ($this->discoverDids($collection, $limit) as $did) {
+                $dids[] = $did;
+                $count++;
+
+                // Start import for this DID
+                $this->importService->import($did, [$collection]);
+
+                if ($onProgress) {
+                    $onProgress($did, $count);
+                }
+            }
+
+            $incomplete = $limit !== null && count($dids) >= $limit;
+
+            return DiscoveryResult::success($dids, $incomplete);
+        } catch (Throwable $e) {
+            return DiscoveryResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * Count total DIDs with records in a collection.
+     *
+     * Note: This iterates through all results, which can be slow.
+     */
+    public function count(string|BackedEnum $collection): int
+    {
+        $count = 0;
+
+        foreach ($this->discoverDids($collection) as $_) {
+            $count++;
+        }
+
+        return $count;
+    }
+}

src/Events/ConflictDetected.php

···
+<?php
+
+namespace SocialDept\AtpParity\Events;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Foundation\Events\Dispatchable;
+use SocialDept\AtpParity\Sync\PendingConflict;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Dispatched when a conflict is detected that requires manual resolution.
+ */
+class ConflictDetected
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Model $model,
+        public readonly Data $record,
+        public readonly array $meta,
+        public readonly PendingConflict $conflict,
+    ) {}
+}

src/Events/ImportCompleted.php

···
+<?php
+
+namespace SocialDept\AtpParity\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use SocialDept\AtpParity\Import\ImportResult;
+
+class ImportCompleted
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly ImportResult $result,
+    ) {}
+}

src/Events/ImportFailed.php

···
+<?php
+
+namespace SocialDept\AtpParity\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+
+class ImportFailed
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly string $did,
+        public readonly string $collection,
+        public readonly string $error,
+    ) {}
+}

src/Events/ImportProgress.php

···
+<?php
+
+namespace SocialDept\AtpParity\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+
+class ImportProgress
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly string $did,
+        public readonly string $collection,
+        public readonly int $recordsSynced,
+        public readonly ?string $cursor = null,
+    ) {}
+}

src/Events/ImportStarted.php

···
+<?php
+
+namespace SocialDept\AtpParity\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+
+class ImportStarted
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly string $did,
+        public readonly string $collection,
+    ) {}
+}

src/Events/RecordPublished.php

···
+<?php
+
+namespace SocialDept\AtpParity\Events;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Foundation\Events\Dispatchable;
+
+/**
+ * Dispatched when a model is published to AT Protocol.
+ */
+class RecordPublished
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Model $model,
+        public readonly string $uri,
+        public readonly string $cid,
+    ) {}
+}

src/Events/RecordUnpublished.php

···
+<?php
+
+namespace SocialDept\AtpParity\Events;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Foundation\Events\Dispatchable;
+
+/**
+ * Dispatched when a model is unpublished from AT Protocol.
+ */
+class RecordUnpublished
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Model $model,
+        public readonly string $uri,
+    ) {}
+}

src/Export/ExportResult.php

···
+<?php
+
+namespace SocialDept\AtpParity\Export;
+
+/**
+ * Value object representing the result of an export operation.
+ */
+readonly class ExportResult
+{
+    public function __construct(
+        public bool $success,
+        public ?string $path = null,
+        public ?int $size = null,
+        public ?string $error = null,
+    ) {}
+
+    /**
+     * Check if the export operation succeeded.
+     */
+    public function isSuccess(): bool
+    {
+        return $this->success;
+    }
+
+    /**
+     * Check if the export operation failed.
+     */
+    public function isFailed(): bool
+    {
+        return ! $this->success;
+    }
+
+    /**
+     * Create a successful result.
+     */
+    public static function success(string $path, int $size): self
+    {
+        return new self(
+            success: true,
+            path: $path,
+            size: $size,
+        );
+    }
+
+    /**
+     * Create a failed result.
+     */
+    public static function failed(string $error): self
+    {
+        return new self(
+            success: false,
+            error: $error,
+        );
+    }
+}

src/Export/ExportService.php

···
+<?php
+
+namespace SocialDept\AtpParity\Export;
+
+use BackedEnum;
+use Generator;
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\Import\ImportService;
+use SocialDept\AtpParity\MapperRegistry;
+use Throwable;
+
+/**
+ * Service for exporting AT Protocol repositories.
+ */
+class ExportService
+{
+    public function __construct(
+        protected MapperRegistry $registry,
+        protected ImportService $importService
+    ) {}
+
+    /**
+     * Download a user's repository as CAR data.
+     */
+    public function downloadRepo(string $did, ?string $since = null): RepoExport
+    {
+        $response = Atp::atproto->sync->getRepo($did, $since);
+        $carData = $response->body();
+
+        return new RepoExport(
+            did: $did,
+            carData: $carData,
+            size: strlen($carData),
+        );
+    }
+
+    /**
+     * Export a repository to a local file.
+     */
+    public function exportToFile(string $did, string $path, ?string $since = null): ExportResult
+    {
+        try {
+            $export = $this->downloadRepo($did, $since);
+
+            if (! $export->saveTo($path)) {
+                return ExportResult::failed("Failed to write to file: {$path}");
+            }
+
+            return ExportResult::success($path, $export->size);
+        } catch (Throwable $e) {
+            return ExportResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * Export and import records from a repository.
+     *
+     * This downloads the repository and imports records using the normal import pipeline.
+     * It's useful for bulk importing all records from a user.
+     *
+     * @param  array<string>|null  $collections  Specific collections to import (null = all registered)
+     */
+    public function exportAndImport(
+        string $did,
+        ?array $collections = null,
+        ?callable $onProgress = null
+    ): ExportResult {
+        try {
+            // Use the import service to import the user's records
+            $result = $this->importService->importUser($did, $collections, $onProgress);
+
+            if ($result->isFailed()) {
+                return ExportResult::failed($result->error ?? 'Import failed');
+            }
+
+            return ExportResult::success(
+                path: "imported:{$did}",
+                size: $result->recordsSynced
+            );
+        } catch (Throwable $e) {
+            return ExportResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * List available blobs for a repository.
+     *
+     * @return Generator<string> Yields blob CIDs
+     */
+    public function listBlobs(string $did, ?string $since = null): Generator
+    {
+        $cursor = null;
+
+        do {
+            $response = Atp::atproto->sync->listBlobs(
+                did: $did,
+                since: $since,
+                limit: 500,
+                cursor: $cursor,
+            );
+
+            foreach ($response->cids as $cid) {
+                yield $cid;
+            }
+
+            $cursor = $response->cursor;
+        } while ($cursor !== null);
+    }
+
+    /**
+     * Download a specific blob.
+     */
+    public function downloadBlob(string $did, string $cid): string
+    {
+        $response = Atp::atproto->sync->getBlob($did, $cid);
+
+        return $response->body();
+    }
+
+    /**
+     * Get the latest commit for a repository.
+     */
+    public function getLatestCommit(string $did): array
+    {
+        $commit = Atp::atproto->sync->getLatestCommit($did);
+
+        return [
+            'cid' => $commit->cid,
+            'rev' => $commit->rev,
+        ];
+    }
+
+    /**
+     * Get the hosting status for a repository.
+     */
+    public function getRepoStatus(string $did): array
+    {
+        $status = Atp::atproto->sync->getRepoStatus($did);
+
+        return $status->toArray();
+    }
+}

src/Export/RepoExport.php

···
+<?php
+
+namespace SocialDept\AtpParity\Export;
+
+/**
+ * Value object representing an exported repository as CAR data.
+ */
+readonly class RepoExport
+{
+    public function __construct(
+        public string $did,
+        public string $carData,
+        public int $size,
+    ) {}
+
+    /**
+     * Save the CAR data to a file.
+     */
+    public function saveTo(string $path): bool
+    {
+        return file_put_contents($path, $this->carData) !== false;
+    }
+
+    /**
+     * Get the size in human-readable format.
+     */
+    public function humanSize(): string
+    {
+        $units = ['B', 'KB', 'MB', 'GB'];
+        $size = $this->size;
+        $unit = 0;
+
+        while ($size >= 1024 && $unit < count($units) - 1) {
+            $size /= 1024;
+            $unit++;
+        }
+
+        return round($size, 2).' '.$units[$unit];
+    }
+}

src/Facades/AtpReplicator.php

···
-<?php
-
-namespace SocialDept\AtpReplicator\Facades;
-
-use Illuminate\Support\Facades\Facade;
-
-class AtpReplicator extends Facade
-{
-    /**
-     * Get the registered name of the component.
-     *
-     * @return string
-     */
-    protected static function getFacadeAccessor(): string
-    {
-        return 'atp-replicator';
-    }
-}

src/Facades/Parity.php

···
+<?php
+
+namespace SocialDept\AtpParity\Facades;
+
+use Illuminate\Support\Facades\Facade;
+use SocialDept\AtpParity\Contracts\RecordMapper;
+use SocialDept\AtpParity\MapperRegistry;
+
+/**
+ * @method static void register(RecordMapper $mapper)
+ * @method static RecordMapper|null forRecord(string $recordClass)
+ * @method static RecordMapper|null forModel(string $modelClass)
+ * @method static RecordMapper|null forLexicon(string $nsid)
+ *
+ * @see MapperRegistry
+ */
+class Parity extends Facade
+{
+    protected static function getFacadeAccessor(): string
+    {
+        return 'parity';
+    }
+}

src/Import/ImportResult.php

···
+<?php
+
+namespace SocialDept\AtpParity\Import;
+
+/**
+ * Immutable value object representing the result of an import operation.
+ */
+readonly class ImportResult
+{
+    public function __construct(
+        public string $did,
+        public string $collection,
+        public int $recordsSynced,
+        public int $recordsSkipped,
+        public int $recordsFailed,
+        public bool $completed,
+        public ?string $cursor = null,
+        public ?string $error = null,
+    ) {}
+
+    /**
+     * Check if the import completed successfully.
+     */
+    public function isSuccess(): bool
+    {
+        return $this->completed && $this->error === null;
+    }
+
+    /**
+     * Check if the import was partially completed.
+     */
+    public function isPartial(): bool
+    {
+        return ! $this->completed && $this->recordsSynced > 0;
+    }
+
+    /**
+     * Check if the import failed.
+     */
+    public function isFailed(): bool
+    {
+        return $this->error !== null;
+    }
+
+    /**
+     * Get total records processed.
+     */
+    public function totalProcessed(): int
+    {
+        return $this->recordsSynced + $this->recordsSkipped + $this->recordsFailed;
+    }
+
+    /**
+     * Create a successful result.
+     */
+    public static function success(string $did, string $collection, int $synced, int $skipped = 0, int $failed = 0): self
+    {
+        return new self(
+            did: $did,
+            collection: $collection,
+            recordsSynced: $synced,
+            recordsSkipped: $skipped,
+            recordsFailed: $failed,
+            completed: true,
+        );
+    }
+
+    /**
+     * Create a partial result (incomplete).
+     */
+    public static function partial(string $did, string $collection, int $synced, string $cursor, int $skipped = 0, int $failed = 0): self
+    {
+        return new self(
+            did: $did,
+            collection: $collection,
+            recordsSynced: $synced,
+            recordsSkipped: $skipped,
+            recordsFailed: $failed,
+            completed: false,
+            cursor: $cursor,
+        );
+    }
+
+    /**
+     * Create a failed result.
+     */
+    public static function failed(string $did, string $collection, string $error, int $synced = 0, int $skipped = 0, int $failed = 0, ?string $cursor = null): self
+    {
+        return new self(
+            did: $did,
+            collection: $collection,
+            recordsSynced: $synced,
+            recordsSkipped: $skipped,
+            recordsFailed: $failed,
+            completed: false,
+            cursor: $cursor,
+            error: $error,
+        );
+    }
+
+    /**
+     * Merge multiple results for the same DID into one aggregate result.
+     *
+     * @param  ImportResult[]  $results
+     */
+    public static function aggregate(string $did, array $results): self
+    {
+        $synced = 0;
+        $skipped = 0;
+        $failed = 0;
+        $errors = [];
+        $allCompleted = true;
+
+        foreach ($results as $result) {
+            $synced += $result->recordsSynced;
+            $skipped += $result->recordsSkipped;
+            $failed += $result->recordsFailed;
+
+            if (! $result->completed) {
+                $allCompleted = false;
+            }
+
+            if ($result->error) {
+                $errors[] = "{$result->collection}: {$result->error}";
+            }
+        }
+
+        return new self(
+            did: $did,
+            collection: '*',
+            recordsSynced: $synced,
+            recordsSkipped: $skipped,
+            recordsFailed: $failed,
+            completed: $allCompleted,
+            error: $errors ? implode('; ', $errors) : null,
+        );
+    }
+}

src/Import/ImportService.php

···
+<?php
+
+namespace SocialDept\AtpParity\Import;
+
+use SocialDept\AtpClient\AtpClient;
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\Events\ImportCompleted;
+use SocialDept\AtpParity\Events\ImportFailed;
+use SocialDept\AtpParity\Events\ImportProgress;
+use SocialDept\AtpParity\Events\ImportStarted;
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpResolver\Facades\Resolver;
+use Throwable;
+
+/**
+ * Orchestrates importing of AT Protocol records to Eloquent models.
+ *
+ * Supports importing individual users, specific collections, or entire
+ * networks through cursor-based pagination with progress tracking.
+ */
+class ImportService
+{
+    /**
+     * Cache of clients by PDS endpoint.
+     *
+     * @var array<string, AtpClient>
+     */
+    protected array $clients = [];
+
+    public function __construct(
+        protected MapperRegistry $registry
+    ) {}
+
+    /**
+     * Import all records for a user in registered collections.
+     *
+     * @param  array<string>|null  $collections  Specific collections to import, or null for all registered
+     */
+    public function importUser(string $did, ?array $collections = null, ?callable $onProgress = null): ImportResult
+    {
+        $collections = $collections ?? $this->registry->lexicons();
+        $results = [];
+
+        foreach ($collections as $collection) {
+            if (! $this->registry->hasLexicon($collection)) {
+                continue;
+            }
+
+            $results[] = $this->importUserCollection($did, $collection, $onProgress);
+        }
+
+        return ImportResult::aggregate($did, $results);
+    }
+
+    /**
+     * Import a specific collection for a user.
+     */
+    public function importUserCollection(string $did, string $collection, ?callable $onProgress = null): ImportResult
+    {
+        $mapper = $this->registry->forLexicon($collection);
+
+        if (! $mapper) {
+            return ImportResult::failed($did, $collection, "No mapper registered for collection: {$collection}");
+        }
+
+        $state = ImportState::findOrCreateFor($did, $collection);
+
+        if ($state->isComplete()) {
+            return $state->toResult();
+        }
+
+        $pdsEndpoint = $this->resolvePds($did);
+
+        if (! $pdsEndpoint) {
+            $error = "Could not resolve PDS endpoint for DID: {$did}";
+            $state->markFailed($error);
+            event(new ImportFailed($did, $collection, $error));
+
+            return ImportResult::failed($did, $collection, $error);
+        }
+
+        $state->markStarted();
+        event(new ImportStarted($did, $collection));
+
+        $client = $this->clientFor($pdsEndpoint);
+        $cursor = $state->cursor;
+        $pageSize = config('parity.import.page_size', 100);
+        $pageDelay = config('parity.import.page_delay', 100);
+        $recordClass = $mapper->recordClass();
+
+        try {
+            do {
+                $response = $client->atproto->repo->listRecords(
+                    repo: $did,
+                    collection: $collection,
+                    limit: $pageSize,
+                    cursor: $cursor
+                );
+
+                $synced = 0;
+                $skipped = 0;
+                $failed = 0;
+
+                foreach ($response->records as $item) {
+                    try {
+                        $record = $recordClass::fromArray($item['value']);
+
+                        $mapper->upsert($record, [
+                            'uri' => $item['uri'],
+                            'cid' => $item['cid'],
+                        ]);
+
+                        $synced++;
+                    } catch (Throwable $e) {
+                        $failed++;
+                    }
+                }
+
+                $cursor = $response->cursor;
+                $state->updateProgress($synced, $skipped, $failed, $cursor);
+
+                if ($onProgress) {
+                    $onProgress(new ImportProgress(
+                        did: $did,
+                        collection: $collection,
+                        recordsSynced: $state->records_synced,
+                        cursor: $cursor
+                    ));
+                }
+
+                event(new ImportProgress($did, $collection, $state->records_synced, $cursor));
+
+                if ($cursor && $pageDelay > 0) {
+                    usleep($pageDelay * 1000);
+                }
+            } while ($cursor);
+
+            $state->markCompleted();
+            $result = $state->toResult();
+            event(new ImportCompleted($result));
+
+            return $result;
+        } catch (Throwable $e) {
+            $error = $e->getMessage();
+            $state->markFailed($error);
+            event(new ImportFailed($did, $collection, $error));
+
+            return ImportResult::failed(
+                did: $did,
+                collection: $collection,
+                error: $error,
+                synced: $state->records_synced,
+                skipped: $state->records_skipped,
+                failed: $state->records_failed,
+                cursor: $state->cursor
+            );
+        }
+    }
+
+    /**
+     * Resume an interrupted import from cursor.
+     */
+    public function resume(ImportState $state, ?callable $onProgress = null): ImportResult
+    {
+        if (! $state->canResume()) {
+            return $state->toResult();
+        }
+
+        $state->update(['status' => ImportState::STATUS_PENDING]);
+
+        return $this->importUserCollection($state->did, $state->collection, $onProgress);
+    }
+
+    /**
+     * Resume all interrupted imports.
+     *
+     * @return array<ImportResult>
+     */
+    public function resumeAll(?callable $onProgress = null): array
+    {
+        $results = [];
+
+        ImportState::resumable()->each(function (ImportState $state) use (&$results, $onProgress) {
+            $results[] = $this->resume($state, $onProgress);
+        });
+
+        return $results;
+    }
+
+    /**
+     * Get import status for a DID/collection.
+     */
+    public function getStatus(string $did, string $collection): ?ImportState
+    {
+        return ImportState::where('did', $did)
+            ->where('collection', $collection)
+            ->first();
+    }
+
+    /**
+     * Get all import states for a DID.
+     *
+     * @return \Illuminate\Database\Eloquent\Collection<int, ImportState>
+     */
+    public function getStatusForUser(string $did): \Illuminate\Database\Eloquent\Collection
+    {
+        return ImportState::where('did', $did)->get();
+    }
+
+    /**
+     * Check if a user's collection has been imported.
+     */
+    public function isImported(string $did, string $collection): bool
+    {
+        $state = $this->getStatus($did, $collection);
+
+        return $state && $state->isComplete();
+    }
+
+    /**
+     * Reset an import state to allow re-importing.
+     */
+    public function reset(string $did, string $collection): void
+    {
+        ImportState::where('did', $did)
+            ->where('collection', $collection)
+            ->delete();
+    }
+
+    /**
+     * Reset all import states for a user.
+     */
+    public function resetUser(string $did): void
+    {
+        ImportState::where('did', $did)->delete();
+    }
+
+    /**
+     * Get or create a client for a PDS endpoint.
+     */
+    protected function clientFor(string $pdsEndpoint): AtpClient
+    {
+        return $this->clients[$pdsEndpoint] ??= Atp::public($pdsEndpoint);
+    }
+
+    /**
+     * Resolve the PDS endpoint for a DID.
+     */
+    protected function resolvePds(string $did): ?string
+    {
+        return Resolver::resolvePds($did);
+    }
+}

src/Import/ImportState.php

···
+<?php
+
+namespace SocialDept\AtpParity\Import;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Tracks import progress for a DID/collection pair.
+ *
+ * @property int $id
+ * @property string $did
+ * @property string $collection
+ * @property string $status
+ * @property string|null $cursor
+ * @property int $records_synced
+ * @property int $records_skipped
+ * @property int $records_failed
+ * @property \Carbon\Carbon|null $started_at
+ * @property \Carbon\Carbon|null $completed_at
+ * @property string|null $error
+ * @property \Carbon\Carbon $created_at
+ * @property \Carbon\Carbon $updated_at
+ */
+class ImportState extends Model
+{
+    public const STATUS_PENDING = 'pending';
+
+    public const STATUS_IN_PROGRESS = 'in_progress';
+
+    public const STATUS_COMPLETED = 'completed';
+
+    public const STATUS_FAILED = 'failed';
+
+    protected $fillable = [
+        'did',
+        'collection',
+        'status',
+        'cursor',
+        'records_synced',
+        'records_skipped',
+        'records_failed',
+        'started_at',
+        'completed_at',
+        'error',
+    ];
+
+    protected $casts = [
+        'records_synced' => 'integer',
+        'records_skipped' => 'integer',
+        'records_failed' => 'integer',
+        'started_at' => 'datetime',
+        'completed_at' => 'datetime',
+    ];
+
+    public function getTable(): string
+    {
+        return config('parity.import.state_table', 'parity_import_states');
+    }
+
+    /**
+     * Start the import process for this state.
+     */
+    public function markStarted(): self
+    {
+        $this->update([
+            'status' => self::STATUS_IN_PROGRESS,
+            'started_at' => now(),
+            'error' => null,
+        ]);
+
+        return $this;
+    }
+
+    /**
+     * Mark the import as completed.
+     */
+    public function markCompleted(): self
+    {
+        $this->update([
+            'status' => self::STATUS_COMPLETED,
+            'completed_at' => now(),
+            'cursor' => null,
+        ]);
+
+        return $this;
+    }
+
+    /**
+     * Mark the import as failed.
+     */
+    public function markFailed(string $error): self
+    {
+        $this->update([
+            'status' => self::STATUS_FAILED,
+            'error' => $error,
+        ]);
+
+        return $this;
+    }
+
+    /**
+     * Update progress during import.
+     */
+    public function updateProgress(int $synced, int $skipped = 0, int $failed = 0, ?string $cursor = null): self
+    {
+        $this->increment('records_synced', $synced);
+
+        if ($skipped > 0) {
+            $this->increment('records_skipped', $skipped);
+        }
+
+        if ($failed > 0) {
+            $this->increment('records_failed', $failed);
+        }
+
+        if ($cursor !== null) {
+            $this->update(['cursor' => $cursor]);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Check if this import can be resumed.
+     */
+    public function canResume(): bool
+    {
+        return $this->status === self::STATUS_IN_PROGRESS
+            || $this->status === self::STATUS_FAILED;
+    }
+
+    /**
+     * Check if this import is complete.
+     */
+    public function isComplete(): bool
+    {
+        return $this->status === self::STATUS_COMPLETED;
+    }
+
+    /**
+     * Check if this import is currently running.
+     */
+    public function isRunning(): bool
+    {
+        return $this->status === self::STATUS_IN_PROGRESS;
+    }
+
+    /**
+     * Scope to pending imports.
+     */
+    public function scopePending(Builder $query): Builder
+    {
+        return $query->where('status', self::STATUS_PENDING);
+    }
+
+    /**
+     * Scope to in-progress imports.
+     */
+    public function scopeInProgress(Builder $query): Builder
+    {
+        return $query->where('status', self::STATUS_IN_PROGRESS);
+    }
+
+    /**
+     * Scope to completed imports.
+     */
+    public function scopeCompleted(Builder $query): Builder
+    {
+        return $query->where('status', self::STATUS_COMPLETED);
+    }
+
+    /**
+     * Scope to failed imports.
+     */
+    public function scopeFailed(Builder $query): Builder
+    {
+        return $query->where('status', self::STATUS_FAILED);
+    }
+
+    /**
+     * Scope to incomplete imports (pending, in_progress, or failed).
+     */
+    public function scopeIncomplete(Builder $query): Builder
+    {
+        return $query->whereIn('status', [
+            self::STATUS_PENDING,
+            self::STATUS_IN_PROGRESS,
+            self::STATUS_FAILED,
+        ]);
+    }
+
+    /**
+     * Scope to resumable imports (in_progress or failed with cursor).
+     */
+    public function scopeResumable(Builder $query): Builder
+    {
+        return $query->whereIn('status', [
+            self::STATUS_IN_PROGRESS,
+            self::STATUS_FAILED,
+        ]);
+    }
+
+    /**
+     * Find or create an import state for a DID/collection pair.
+     */
+    public static function findOrCreateFor(string $did, string $collection): self
+    {
+        return static::firstOrCreate(
+            ['did' => $did, 'collection' => $collection],
+            ['status' => self::STATUS_PENDING]
+        );
+    }
+
+    /**
+     * Convert to ImportResult.
+     */
+    public function toResult(): ImportResult
+    {
+        return new ImportResult(
+            did: $this->did,
+            collection: $this->collection,
+            recordsSynced: $this->records_synced,
+            recordsSkipped: $this->records_skipped,
+            recordsFailed: $this->records_failed,
+            completed: $this->isComplete(),
+            cursor: $this->cursor,
+            error: $this->error,
+        );
+    }
+}

src/Jobs/ImportUserJob.php

···
+<?php
+
+namespace SocialDept\AtpParity\Jobs;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use SocialDept\AtpParity\Import\ImportService;
+
+class ImportUserJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    /**
+     * The number of times the job may be attempted.
+     */
+    public int $tries = 3;
+
+    /**
+     * The number of seconds to wait before retrying.
+     */
+    public int $backoff = 60;
+
+    public function __construct(
+        public string $did,
+        public ?string $collection = null,
+    ) {
+        $this->onQueue(config('parity.import.queue', 'default'));
+    }
+
+    public function handle(ImportService $service): void
+    {
+        $collections = $this->collection ? [$this->collection] : null;
+        $service->importUser($this->did, $collections);
+    }
+
+    /**
+     * Get the tags that should be assigned to the job.
+     *
+     * @return array<string>
+     */
+    public function tags(): array
+    {
+        $tags = ['parity-import', "did:{$this->did}"];
+
+        if ($this->collection) {
+            $tags[] = "collection:{$this->collection}";
+        }
+
+        return $tags;
+    }
+}

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/ParityServiceProvider.php

···
+<?php
+
+namespace SocialDept\AtpParity;
+
+use Illuminate\Support\ServiceProvider;
+use SocialDept\AtpParity\Commands\DiscoverCommand;
+use SocialDept\AtpParity\Commands\ExportCommand;
+use SocialDept\AtpParity\Commands\ImportCommand;
+use SocialDept\AtpParity\Commands\ImportStatusCommand;
+use SocialDept\AtpParity\Discovery\DiscoveryService;
+use SocialDept\AtpParity\Export\ExportService;
+use SocialDept\AtpParity\Import\ImportService;
+use SocialDept\AtpParity\Publish\PublishService;
+use SocialDept\AtpParity\Support\RecordHelper;
+
+class ParityServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        $this->registerConfiguredMappers();
+
+        if ($this->app->runningInConsole()) {
+            $this->bootForConsole();
+        }
+    }
+
+    public function register(): void
+    {
+        $this->mergeConfigFrom(__DIR__.'/../config/parity.php', 'parity');
+
+        $this->app->singleton(MapperRegistry::class);
+        $this->app->alias(MapperRegistry::class, 'parity');
+
+        $this->app->singleton(RecordHelper::class, function ($app) {
+            return new RecordHelper($app->make(MapperRegistry::class));
+        });
+
+        $this->app->singleton(ImportService::class, function ($app) {
+            return new ImportService($app->make(MapperRegistry::class));
+        });
+
+        $this->app->singleton(PublishService::class, function ($app) {
+            return new PublishService($app->make(MapperRegistry::class));
+        });
+
+        $this->app->singleton(DiscoveryService::class, function ($app) {
+            return new DiscoveryService($app->make(ImportService::class));
+        });
+
+        $this->app->singleton(ExportService::class, function ($app) {
+            return new ExportService(
+                $app->make(MapperRegistry::class),
+                $app->make(ImportService::class)
+            );
+        });
+    }
+
+    /**
+     * Register mappers defined in config.
+     */
+    protected function registerConfiguredMappers(): void
+    {
+        $registry = $this->app->make(MapperRegistry::class);
+
+        foreach (config('parity.mappers', []) as $mapperClass) {
+            if (class_exists($mapperClass)) {
+                $registry->register($this->app->make($mapperClass));
+            }
+        }
+    }
+
+    protected function bootForConsole(): void
+    {
+        $this->publishes([
+            __DIR__.'/../config/parity.php' => config_path('parity.php'),
+        ], 'parity-config');
+
+        $this->publishes([
+            __DIR__.'/../database/migrations' => database_path('migrations'),
+        ], 'parity-migrations');
+
+        $this->commands([
+            DiscoverCommand::class,
+            ExportCommand::class,
+            ImportCommand::class,
+            ImportStatusCommand::class,
+        ]);
+    }
+
+    public function provides(): array
+    {
+        return [
+            'parity',
+            MapperRegistry::class,
+            RecordHelper::class,
+            ImportService::class,
+            PublishService::class,
+            DiscoveryService::class,
+            ExportService::class,
+        ];
+    }
+}

src/Publish/PublishResult.php

···
+<?php
+
+namespace SocialDept\AtpParity\Publish;
+
+/**
+ * Immutable value object representing the result of a publish operation.
+ */
+readonly class PublishResult
+{
+    public function __construct(
+        public bool $success,
+        public ?string $uri = null,
+        public ?string $cid = null,
+        public ?string $error = null,
+    ) {}
+
+    /**
+     * Check if the publish operation succeeded.
+     */
+    public function isSuccess(): bool
+    {
+        return $this->success;
+    }
+
+    /**
+     * Check if the publish operation failed.
+     */
+    public function isFailed(): bool
+    {
+        return ! $this->success;
+    }
+
+    /**
+     * Create a successful result.
+     */
+    public static function success(string $uri, string $cid): self
+    {
+        return new self(
+            success: true,
+            uri: $uri,
+            cid: $cid,
+        );
+    }
+
+    /**
+     * Create a failed result.
+     */
+    public static function failed(string $error): self
+    {
+        return new self(
+            success: false,
+            error: $error,
+        );
+    }
+}

src/Publish/PublishService.php

···
+<?php
+
+namespace SocialDept\AtpParity\Publish;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\Events\RecordPublished;
+use SocialDept\AtpParity\Events\RecordUnpublished;
+use SocialDept\AtpParity\MapperRegistry;
+use Throwable;
+
+/**
+ * Service for publishing Eloquent models to AT Protocol.
+ */
+class PublishService
+{
+    public function __construct(
+        protected MapperRegistry $registry
+    ) {}
+
+    /**
+     * Publish a model as a new record to AT Protocol.
+     *
+     * Requires the model to have a DID association (via did column or relationship).
+     */
+    public function publish(Model $model): PublishResult
+    {
+        $did = $this->getDidFromModel($model);
+
+        if (! $did) {
+            return PublishResult::failed('No DID associated with model. Use publishAs() to specify a DID.');
+        }
+
+        return $this->publishAs($did, $model);
+    }
+
+    /**
+     * Publish a model as a specific user.
+     */
+    public function publishAs(string $did, Model $model): PublishResult
+    {
+        $mapper = $this->registry->forModel(get_class($model));
+
+        if (! $mapper) {
+            return PublishResult::failed('No mapper registered for model: '.get_class($model));
+        }
+
+        // Check if already published
+        $existingUri = $this->getModelUri($model);
+        if ($existingUri) {
+            return $this->update($model);
+        }
+
+        try {
+            $record = $mapper->toRecord($model);
+            $collection = $mapper->lexicon();
+
+            $client = Atp::as($did);
+            $response = $client->atproto->repo->createRecord(
+                repo: $did,
+                collection: $collection,
+                record: $record->toArray(),
+            );
+
+            // Update model with ATP metadata
+            $this->updateModelMeta($model, $response->uri, $response->cid);
+
+            event(new RecordPublished($model, $response->uri, $response->cid));
+
+            return PublishResult::success($response->uri, $response->cid);
+        } catch (Throwable $e) {
+            return PublishResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * Update an existing published record.
+     */
+    public function update(Model $model): PublishResult
+    {
+        $uri = $this->getModelUri($model);
+
+        if (! $uri) {
+            return PublishResult::failed('Model has not been published yet. Use publish() first.');
+        }
+
+        $mapper = $this->registry->forModel(get_class($model));
+
+        if (! $mapper) {
+            return PublishResult::failed('No mapper registered for model: '.get_class($model));
+        }
+
+        $parts = $this->parseUri($uri);
+
+        if (! $parts) {
+            return PublishResult::failed('Invalid AT Protocol URI: '.$uri);
+        }
+
+        try {
+            $record = $mapper->toRecord($model);
+
+            $client = Atp::as($parts['did']);
+            $response = $client->atproto->repo->putRecord(
+                repo: $parts['did'],
+                collection: $parts['collection'],
+                rkey: $parts['rkey'],
+                record: $record->toArray(),
+            );
+
+            // Update model with new CID
+            $this->updateModelMeta($model, $response->uri, $response->cid);
+
+            event(new RecordPublished($model, $response->uri, $response->cid));
+
+            return PublishResult::success($response->uri, $response->cid);
+        } catch (Throwable $e) {
+            return PublishResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * Delete a published record from AT Protocol.
+     */
+    public function delete(Model $model): bool
+    {
+        $uri = $this->getModelUri($model);
+
+        if (! $uri) {
+            return false;
+        }
+
+        $parts = $this->parseUri($uri);
+
+        if (! $parts) {
+            return false;
+        }
+
+        try {
+            $client = Atp::as($parts['did']);
+            $client->atproto->repo->deleteRecord(
+                repo: $parts['did'],
+                collection: $parts['collection'],
+                rkey: $parts['rkey'],
+            );
+
+            // Clear ATP metadata from model
+            $this->clearModelMeta($model);
+
+            event(new RecordUnpublished($model, $uri));
+
+            return true;
+        } catch (Throwable $e) {
+            return false;
+        }
+    }
+
+    /**
+     * Get the DID from a model.
+     *
+     * Override this method or set a did column/relationship on your model.
+     */
+    protected function getDidFromModel(Model $model): ?string
+    {
+        // Check for did column
+        if (isset($model->did)) {
+            return $model->did;
+        }
+
+        // Check for user relationship with did
+        if (method_exists($model, 'user') && $model->user?->did) {
+            return $model->user->did;
+        }
+
+        // Check for author relationship with did
+        if (method_exists($model, 'author') && $model->author?->did) {
+            return $model->author->did;
+        }
+
+        // Try extracting from existing URI
+        $uri = $this->getModelUri($model);
+        if ($uri) {
+            $parts = $this->parseUri($uri);
+
+            return $parts['did'] ?? null;
+        }
+
+        return null;
+    }
+
+    /**
+     * Get the AT Protocol URI from a model.
+     */
+    protected function getModelUri(Model $model): ?string
+    {
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $model->{$column};
+    }
+
+    /**
+     * Update model with AT Protocol metadata.
+     */
+    protected function updateModelMeta(Model $model, string $uri, string $cid): void
+    {
+        $uriColumn = config('parity.columns.uri', 'atp_uri');
+        $cidColumn = config('parity.columns.cid', 'atp_cid');
+
+        $model->{$uriColumn} = $uri;
+        $model->{$cidColumn} = $cid;
+        $model->save();
+    }
+
+    /**
+     * Clear AT Protocol metadata from model.
+     */
+    protected function clearModelMeta(Model $model): void
+    {
+        $uriColumn = config('parity.columns.uri', 'atp_uri');
+        $cidColumn = config('parity.columns.cid', 'atp_cid');
+
+        $model->{$uriColumn} = null;
+        $model->{$cidColumn} = null;
+        $model->save();
+    }
+
+    /**
+     * Parse an AT Protocol URI into its components.
+     *
+     * @return array{did: string, collection: string, rkey: string}|null
+     */
+    protected function parseUri(string $uri): ?array
+    {
+        if (! preg_match('#^at://([^/]+)/([^/]+)/([^/]+)$#', $uri, $matches)) {
+            return null;
+        }
+
+        return [
+            'did' => $matches[1],
+            'collection' => $matches[2],
+            'rkey' => $matches[3],
+        ];
+    }
+}

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;
+    }
+}

src/Signals/ParitySignal.php

···
+<?php
+
+namespace SocialDept\AtpParity\Signals;
+
+use SocialDept\AtpParity\Contracts\RecordMapper;
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpParity\Sync\ConflictDetector;
+use SocialDept\AtpParity\Sync\ConflictResolver;
+use SocialDept\AtpParity\Sync\ConflictStrategy;
+use SocialDept\AtpSignals\Events\SignalEvent;
+use SocialDept\AtpSignals\Signals\Signal;
+
+/**
+ * Signal that automatically syncs firehose events to Eloquent models.
+ *
+ * This signal listens for commit events on collections that have registered
+ * mappers and automatically creates, updates, or deletes the corresponding
+ * Eloquent models.
+ *
+ * Supports selective sync via configuration or by extending this class:
+ * - Filter by DID: config('parity.sync.dids') or override dids()
+ * - Filter by operation: config('parity.sync.operations') or override operations()
+ * - Custom filter: config('parity.sync.filter') or override shouldSync()
+ *
+ * Supports conflict resolution via configuration:
+ * - Strategy: config('parity.conflicts.strategy') - 'remote', 'local', 'newest', 'manual'
+ *
+ * To use this signal, register it in your atp-signals config:
+ *
+ * // config/signal.php
+ * return [
+ *     'signals' => [
+ *         \SocialDept\AtpParity\Signals\ParitySignal::class,
+ *     ],
+ * ];
+ */
+class ParitySignal extends Signal
+{
+    protected ConflictDetector $conflictDetector;
+
+    protected ConflictResolver $conflictResolver;
+
+    public function __construct(
+        protected MapperRegistry $registry
+    ) {
+        $this->conflictDetector = new ConflictDetector;
+        $this->conflictResolver = new ConflictResolver;
+    }
+
+    /**
+     * Listen for commit events only.
+     */
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    /**
+     * Only listen for collections that have registered mappers.
+     */
+    public function collections(): ?array
+    {
+        $lexicons = $this->registry->lexicons();
+
+        // Return null if no mappers registered (don't match anything)
+        return empty($lexicons) ? ['__none__'] : $lexicons;
+    }
+
+    /**
+     * Get the DIDs to sync (null = all DIDs).
+     *
+     * Override this method for custom DID filtering logic.
+     */
+    public function dids(): ?array
+    {
+        return config('parity.sync.dids');
+    }
+
+    /**
+     * Get the operations to sync (null = all operations).
+     *
+     * Possible values: 'create', 'update', 'delete'
+     * Override this method for custom operation filtering.
+     */
+    public function operations(): ?array
+    {
+        return config('parity.sync.operations');
+    }
+
+    /**
+     * Determine if the event should be synced.
+     *
+     * Override this method for custom filtering logic.
+     */
+    public function shouldSync(SignalEvent $event): bool
+    {
+        // Check custom filter callback from config
+        $filter = config('parity.sync.filter');
+        if ($filter && is_callable($filter)) {
+            return $filter($event);
+        }
+
+        return true;
+    }
+
+    /**
+     * Handle the firehose event.
+     */
+    public function handle(SignalEvent $event): void
+    {
+        if (! $event->commit) {
+            return;
+        }
+
+        // Apply DID filter
+        $dids = $this->dids();
+        if ($dids !== null && ! in_array($event->did, $dids)) {
+            return;
+        }
+
+        $commit = $event->commit;
+
+        // Apply operation filter
+        $operations = $this->operations();
+        if ($operations !== null) {
+            $operation = $this->getOperationType($commit);
+            if (! in_array($operation, $operations)) {
+                return;
+            }
+        }
+
+        // Apply custom filter
+        if (! $this->shouldSync($event)) {
+            return;
+        }
+
+        $mapper = $this->registry->forLexicon($commit->collection);
+
+        if (! $mapper) {
+            return;
+        }
+
+        if ($commit->isCreate() || $commit->isUpdate()) {
+            $this->handleUpsert($event, $mapper);
+        } elseif ($commit->isDelete()) {
+            $this->handleDelete($event, $mapper);
+        }
+    }
+
+    /**
+     * Get the operation type from a commit.
+     */
+    protected function getOperationType(object $commit): string
+    {
+        if ($commit->isCreate()) {
+            return 'create';
+        }
+
+        if ($commit->isUpdate()) {
+            return 'update';
+        }
+
+        if ($commit->isDelete()) {
+            return 'delete';
+        }
+
+        return 'unknown';
+    }
+
+    /**
+     * Handle create or update operations.
+     */
+    protected function handleUpsert(SignalEvent $event, RecordMapper $mapper): void
+    {
+        $commit = $event->commit;
+
+        if (! $commit->record) {
+            return;
+        }
+
+        $recordClass = $mapper->recordClass();
+        $record = $recordClass::fromArray((array) $commit->record);
+
+        $uri = $this->buildUri($event->did, $commit->collection, $commit->rkey);
+        $meta = [
+            'uri' => $uri,
+            'cid' => $commit->cid,
+        ];
+
+        // Check for existing model and potential conflict
+        $existing = $mapper->findByUri($uri);
+
+        if ($existing && $this->conflictDetector->hasConflict($existing, $record, $commit->cid)) {
+            $strategy = ConflictStrategy::fromConfig();
+            $resolution = $this->conflictResolver->resolve(
+                $existing,
+                $record,
+                $meta,
+                $mapper,
+                $strategy
+            );
+
+            // If conflict is pending manual resolution, don't apply changes
+            if (! $resolution->isResolved()) {
+                return;
+            }
+
+            // Conflict was resolved, model already updated if needed
+            return;
+        }
+
+        // No conflict, proceed with normal upsert
+        $mapper->upsert($record, $meta);
+    }
+
+    /**
+     * Handle delete operations.
+     */
+    protected function handleDelete(SignalEvent $event, RecordMapper $mapper): void
+    {
+        $commit = $event->commit;
+        $uri = $this->buildUri($event->did, $commit->collection, $commit->rkey);
+
+        $mapper->deleteByUri($uri);
+    }
+
+    /**
+     * Build an AT Protocol URI.
+     */
+    protected function buildUri(string $did, string $collection, string $rkey): string
+    {
+        return "at://{$did}/{$collection}/{$rkey}";
+    }
+}

src/Support/RecordHelper.php

···
+<?php
+
+namespace SocialDept\AtpParity\Support;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpClient\AtpClient;
+use SocialDept\AtpClient\Data\Responses\Atproto\Repo\GetRecordResponse;
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpResolver\Facades\Resolver;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Helper for integrating atp-parity with atp-client.
+ *
+ * Provides convenient methods for fetching records from the ATP network
+ * and converting them to typed DTOs or Eloquent models.
+ */
+class RecordHelper
+{
+    /**
+     * Cache of clients by PDS endpoint.
+     *
+     * @var array<string, AtpClient>
+     */
+    protected array $clients = [];
+
+    public function __construct(
+        protected MapperRegistry $registry
+    ) {}
+
+    /**
+     * Get or create a client for a PDS endpoint.
+     */
+    protected function clientFor(string $pdsEndpoint): AtpClient
+    {
+        return $this->clients[$pdsEndpoint] ??= Atp::public($pdsEndpoint);
+    }
+
+    /**
+     * Resolve the PDS endpoint for a DID or handle.
+     */
+    protected function resolvePds(string $actor): ?string
+    {
+        return Resolver::resolvePds($actor);
+    }
+
+    /**
+     * Convert a GetRecordResponse to a typed record DTO.
+     *
+     * @template T of Data
+     *
+     * @param  class-string<T>|null  $recordClass  Explicit record class, or null to auto-detect from mapper
+     * @return T|array The typed record, or raw array if no mapper found and no class specified
+     */
+    public function hydrateRecord(GetRecordResponse $response, ?string $recordClass = null): mixed
+    {
+        if ($recordClass) {
+            return $recordClass::fromArray($response->value);
+        }
+
+        $collection = $this->extractCollection($response->uri);
+        $mapper = $this->registry->forLexicon($collection);
+
+        if (! $mapper) {
+            return $response->value;
+        }
+
+        $recordClass = $mapper->recordClass();
+
+        return $recordClass::fromArray($response->value);
+    }
+
+    /**
+     * Fetch a record from the ATP network by URI and return as typed DTO.
+     *
+     * @template T of Data
+     *
+     * @param  class-string<T>|null  $recordClass
+     * @return T|array|null
+     */
+    public function fetch(string $uri, ?string $recordClass = null): mixed
+    {
+        $parts = $this->parseUri($uri);
+
+        if (! $parts) {
+            return null;
+        }
+
+        $pdsEndpoint = $this->resolvePds($parts['repo']);
+
+        if (! $pdsEndpoint) {
+            return null;
+        }
+
+        $response = $this->clientFor($pdsEndpoint)->atproto->repo->getRecord(
+            $parts['repo'],
+            $parts['collection'],
+            $parts['rkey']
+        );
+
+        return $this->hydrateRecord($response, $recordClass);
+    }
+
+    /**
+     * Fetch a record by URI and convert directly to an Eloquent model.
+     *
+     * @template TModel of Model
+     *
+     * @return TModel|null
+     */
+    public function fetchAsModel(string $uri): ?Model
+    {
+        $parts = $this->parseUri($uri);
+
+        if (! $parts) {
+            return null;
+        }
+
+        $mapper = $this->registry->forLexicon($parts['collection']);
+
+        if (! $mapper) {
+            return null;
+        }
+
+        $pdsEndpoint = $this->resolvePds($parts['repo']);
+
+        if (! $pdsEndpoint) {
+            return null;
+        }
+
+        $response = $this->clientFor($pdsEndpoint)->atproto->repo->getRecord(
+            $parts['repo'],
+            $parts['collection'],
+            $parts['rkey']
+        );
+
+        $recordClass = $mapper->recordClass();
+        $record = $recordClass::fromArray($response->value);
+
+        return $mapper->toModel($record, [
+            'uri' => $response->uri,
+            'cid' => $response->cid,
+        ]);
+    }
+
+    /**
+     * Fetch a record by URI and upsert to the database.
+     *
+     * @template TModel of Model
+     *
+     * @return TModel|null
+     */
+    public function sync(string $uri): ?Model
+    {
+        $parts = $this->parseUri($uri);
+
+        if (! $parts) {
+            return null;
+        }
+
+        $mapper = $this->registry->forLexicon($parts['collection']);
+
+        if (! $mapper) {
+            return null;
+        }
+
+        $pdsEndpoint = $this->resolvePds($parts['repo']);
+
+        if (! $pdsEndpoint) {
+            return null;
+        }
+
+        $response = $this->clientFor($pdsEndpoint)->atproto->repo->getRecord(
+            $parts['repo'],
+            $parts['collection'],
+            $parts['rkey']
+        );
+
+        $recordClass = $mapper->recordClass();
+        $record = $recordClass::fromArray($response->value);
+
+        return $mapper->upsert($record, [
+            'uri' => $response->uri,
+            'cid' => $response->cid,
+        ]);
+    }
+
+    /**
+     * Parse an AT Protocol URI into its components.
+     *
+     * @return array{repo: string, collection: string, rkey: string}|null
+     */
+    protected function parseUri(string $uri): ?array
+    {
+        // at://did:plc:xxx/app.bsky.feed.post/rkey
+        if (! preg_match('#^at://([^/]+)/([^/]+)/([^/]+)$#', $uri, $matches)) {
+            return null;
+        }
+
+        return [
+            'repo' => $matches[1],
+            'collection' => $matches[2],
+            'rkey' => $matches[3],
+        ];
+    }
+
+    /**
+     * Extract collection from AT Protocol URI.
+     */
+    protected function extractCollection(string $uri): string
+    {
+        // at://did:plc:xxx/app.bsky.feed.post/rkey
+        if (preg_match('#^at://[^/]+/([^/]+)/#', $uri, $matches)) {
+            return $matches[1];
+        }
+
+        return '';
+    }
+}

src/Support/SchemaMapper.php

···
+<?php
+
+namespace SocialDept\AtpParity\Support;
+
+use Closure;
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\RecordMapper;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Adapter for using atp-schema generated DTOs as record types.
+ *
+ * This allows you to use the auto-generated schema classes directly
+ * without creating custom Record classes.
+ *
+ * Example:
+ *
+ * use SocialDept\AtpSchema\Generated\App\Bsky\Feed\Post;
+ * use App\Models\Post as PostModel;
+ *
+ * $mapper = new SchemaMapper(
+ *     schemaClass: Post::class,
+ *     modelClass: PostModel::class,
+ *     toAttributes: fn(Post $p) => [
+ *         'content' => $p->text,
+ *         'published_at' => $p->createdAt,
+ *     ],
+ *     toRecordData: fn(PostModel $m) => [
+ *         'text' => $m->content,
+ *         'createdAt' => $m->published_at->toIso8601String(),
+ *     ],
+ * );
+ *
+ * $registry->register($mapper);
+ *
+ * @template TSchema of Data
+ * @template TModel of Model
+ *
+ * @extends RecordMapper<TSchema, TModel>
+ */
+class SchemaMapper extends RecordMapper
+{
+    /**
+     * @param  class-string<TSchema>  $schemaClass  The atp-schema generated class
+     * @param  class-string<TModel>  $modelClass  The Eloquent model class
+     * @param  Closure(TSchema): array  $toAttributes  Convert schema to model attributes
+     * @param  Closure(TModel): array  $toRecordData  Convert model to record data
+     */
+    public function __construct(
+        protected string $schemaClass,
+        protected string $modelClass,
+        protected Closure $toAttributes,
+        protected Closure $toRecordData,
+    ) {}
+
+    public function recordClass(): string
+    {
+        return $this->schemaClass;
+    }
+
+    public function modelClass(): string
+    {
+        return $this->modelClass;
+    }
+
+    protected function recordToAttributes(Data $record): array
+    {
+        return ($this->toAttributes)($record);
+    }
+
+    protected function modelToRecordData(Model $model): array
+    {
+        return ($this->toRecordData)($model);
+    }
+}

src/Sync/ConflictDetector.php

···
+<?php
+
+namespace SocialDept\AtpParity\Sync;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\Concerns\SyncsWithAtp;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Detects conflicts between local and remote record versions.
+ */
+class ConflictDetector
+{
+    /**
+     * Check if there's a conflict between local model and remote record.
+     */
+    public function hasConflict(Model $model, Data $record, string $cid): bool
+    {
+        // No conflict if model doesn't have local changes
+        if (! $this->modelHasLocalChanges($model)) {
+            return false;
+        }
+
+        // No conflict if CID matches (same version)
+        if ($this->getCid($model) === $cid) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Check if the model has local changes since last sync.
+     */
+    protected function modelHasLocalChanges(Model $model): bool
+    {
+        // Use trait method if available
+        if ($this->usesTrait($model, SyncsWithAtp::class)) {
+            return $model->hasLocalChanges();
+        }
+
+        // Fallback: compare updated_at with a sync timestamp if available
+        $syncedAt = $model->getAttribute('atp_synced_at');
+
+        if (! $syncedAt) {
+            return true;
+        }
+
+        $updatedAt = $model->getAttribute('updated_at');
+
+        if (! $updatedAt) {
+            return false;
+        }
+
+        return $updatedAt > $syncedAt;
+    }
+
+    /**
+     * Get the CID from a model.
+     */
+    protected function getCid(Model $model): ?string
+    {
+        $column = config('parity.columns.cid', 'atp_cid');
+
+        return $model->getAttribute($column);
+    }
+
+    /**
+     * Check if a model uses a specific trait.
+     *
+     * @param  class-string  $trait
+     */
+    protected function usesTrait(Model $model, string $trait): bool
+    {
+        return in_array($trait, class_uses_recursive($model));
+    }
+}

src/Sync/ConflictResolution.php

···
+<?php
+
+namespace SocialDept\AtpParity\Sync;
+
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Value object representing the result of conflict resolution.
+ */
+readonly class ConflictResolution
+{
+    public function __construct(
+        public bool $resolved,
+        public string $winner,
+        public ?Model $model = null,
+        public ?PendingConflict $pending = null,
+    ) {}
+
+    /**
+     * Check if the conflict was resolved.
+     */
+    public function isResolved(): bool
+    {
+        return $this->resolved;
+    }
+
+    /**
+     * Check if the conflict requires manual resolution.
+     */
+    public function isPending(): bool
+    {
+        return ! $this->resolved && $this->pending !== null;
+    }
+
+    /**
+     * Create resolution where remote wins.
+     */
+    public static function remoteWins(Model $model): self
+    {
+        return new self(
+            resolved: true,
+            winner: 'remote',
+            model: $model,
+        );
+    }
+
+    /**
+     * Create resolution where local wins.
+     */
+    public static function localWins(Model $model): self
+    {
+        return new self(
+            resolved: true,
+            winner: 'local',
+            model: $model,
+        );
+    }
+
+    /**
+     * Create pending resolution for manual review.
+     */
+    public static function pending(PendingConflict $conflict): self
+    {
+        return new self(
+            resolved: false,
+            winner: 'manual',
+            pending: $conflict,
+        );
+    }
+}

src/Sync/ConflictResolver.php

···
+<?php
+
+namespace SocialDept\AtpParity\Sync;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\Contracts\RecordMapper;
+use SocialDept\AtpParity\Events\ConflictDetected;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Resolves conflicts between local and remote record versions.
+ */
+class ConflictResolver
+{
+    /**
+     * Resolve a conflict according to the specified strategy.
+     */
+    public function resolve(
+        Model $model,
+        Data $record,
+        array $meta,
+        RecordMapper $mapper,
+        ConflictStrategy $strategy
+    ): ConflictResolution {
+        return match ($strategy) {
+            ConflictStrategy::RemoteWins => $this->applyRemote($model, $record, $meta, $mapper),
+            ConflictStrategy::LocalWins => $this->keepLocal($model),
+            ConflictStrategy::NewestWins => $this->compareAndApply($model, $record, $meta, $mapper),
+            ConflictStrategy::Manual => $this->flagForReview($model, $record, $meta, $mapper),
+        };
+    }
+
+    /**
+     * Apply the remote version, overwriting local changes.
+     */
+    protected function applyRemote(
+        Model $model,
+        Data $record,
+        array $meta,
+        RecordMapper $mapper
+    ): ConflictResolution {
+        $mapper->updateModel($model, $record, $meta);
+        $model->save();
+
+        return ConflictResolution::remoteWins($model);
+    }
+
+    /**
+     * Keep the local version, ignoring remote changes.
+     */
+    protected function keepLocal(Model $model): ConflictResolution
+    {
+        return ConflictResolution::localWins($model);
+    }
+
+    /**
+     * Compare timestamps and apply the newest version.
+     */
+    protected function compareAndApply(
+        Model $model,
+        Data $record,
+        array $meta,
+        RecordMapper $mapper
+    ): ConflictResolution {
+        $localUpdatedAt = $model->getAttribute('updated_at');
+
+        // Try to get remote timestamp from record
+        $remoteCreatedAt = $record->createdAt ?? null;
+
+        // If we can't compare, default to remote wins
+        if (! $localUpdatedAt || ! $remoteCreatedAt) {
+            return $this->applyRemote($model, $record, $meta, $mapper);
+        }
+
+        // Compare timestamps
+        if ($localUpdatedAt > $remoteCreatedAt) {
+            return $this->keepLocal($model);
+        }
+
+        return $this->applyRemote($model, $record, $meta, $mapper);
+    }
+
+    /**
+     * Flag the conflict for manual review.
+     */
+    protected function flagForReview(
+        Model $model,
+        Data $record,
+        array $meta,
+        RecordMapper $mapper
+    ): ConflictResolution {
+        // Create a pending conflict record
+        $conflict = PendingConflict::create([
+            'model_type' => get_class($model),
+            'model_id' => $model->getKey(),
+            'uri' => $meta['uri'] ?? null,
+            'local_data' => $model->toArray(),
+            'remote_data' => $this->buildRemoteData($record, $meta, $mapper),
+            'status' => 'pending',
+        ]);
+
+        // Dispatch event for notification
+        event(new ConflictDetected($model, $record, $meta, $conflict));
+
+        return ConflictResolution::pending($conflict);
+    }
+
+    /**
+     * Build the remote data array for storage.
+     */
+    protected function buildRemoteData(Data $record, array $meta, RecordMapper $mapper): array
+    {
+        // Create a temporary model with the remote data
+        $tempModel = $mapper->toModel($record, $meta);
+
+        return $tempModel->toArray();
+    }
+}

src/Sync/ConflictStrategy.php

···
+<?php
+
+namespace SocialDept\AtpParity\Sync;
+
+/**
+ * Strategy for resolving conflicts between local and remote changes.
+ */
+enum ConflictStrategy: string
+{
+    /**
+     * Remote (AT Protocol) is source of truth.
+     * Local changes are overwritten.
+     */
+    case RemoteWins = 'remote';
+
+    /**
+     * Local database is source of truth.
+     * Remote changes are ignored.
+     */
+    case LocalWins = 'local';
+
+    /**
+     * Compare timestamps and use the newest version.
+     */
+    case NewestWins = 'newest';
+
+    /**
+     * Flag conflict for manual review.
+     * Neither version is applied automatically.
+     */
+    case Manual = 'manual';
+
+    /**
+     * Create from config value.
+     */
+    public static function fromConfig(): self
+    {
+        $strategy = config('parity.conflicts.strategy', 'remote');
+
+        return self::tryFrom($strategy) ?? self::RemoteWins;
+    }
+}

src/Sync/PendingConflict.php

···
+<?php
+
+namespace SocialDept\AtpParity\Sync;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+
+/**
+ * Model for storing pending conflicts requiring manual resolution.
+ */
+class PendingConflict extends Model
+{
+    protected $guarded = [];
+
+    protected $casts = [
+        'local_data' => 'array',
+        'remote_data' => 'array',
+        'resolved_at' => 'datetime',
+    ];
+
+    /**
+     * Get the table name from config.
+     */
+    public function getTable(): string
+    {
+        return config('parity.conflicts.table', 'parity_conflicts');
+    }
+
+    /**
+     * Get the related model.
+     */
+    public function model(): MorphTo
+    {
+        return $this->morphTo();
+    }
+
+    /**
+     * Check if this conflict is pending.
+     */
+    public function isPending(): bool
+    {
+        return $this->status === 'pending';
+    }
+
+    /**
+     * Check if this conflict has been resolved.
+     */
+    public function isResolved(): bool
+    {
+        return $this->status === 'resolved';
+    }
+
+    /**
+     * Check if this conflict was dismissed.
+     */
+    public function isDismissed(): bool
+    {
+        return $this->status === 'dismissed';
+    }
+
+    /**
+     * Resolve the conflict with the local version.
+     */
+    public function resolveWithLocal(): void
+    {
+        $this->update([
+            'status' => 'resolved',
+            'resolution' => 'local',
+            'resolved_at' => now(),
+        ]);
+    }
+
+    /**
+     * Resolve the conflict with the remote version.
+     */
+    public function resolveWithRemote(): void
+    {
+        $model = $this->model;
+
+        if ($model) {
+            $model->fill($this->remote_data);
+            $model->save();
+        }
+
+        $this->update([
+            'status' => 'resolved',
+            'resolution' => 'remote',
+            'resolved_at' => now(),
+        ]);
+    }
+
+    /**
+     * Dismiss this conflict without resolving.
+     */
+    public function dismiss(): void
+    {
+        $this->update([
+            'status' => 'dismissed',
+            'resolved_at' => now(),
+        ]);
+    }
+
+    /**
+     * Scope to pending conflicts.
+     */
+    public function scopePending($query)
+    {
+        return $query->where('status', 'pending');
+    }
+
+    /**
+     * Scope to resolved conflicts.
+     */
+    public function scopeResolved($query)
+    {
+        return $query->where('status', 'resolved');
+    }
+
+    /**
+     * Scope to conflicts for a specific model.
+     */
+    public function scopeForModel($query, Model $model)
+    {
+        return $query->where('model_type', get_class($model))
+            ->where('model_id', $model->getKey());
+    }
+}

tests/Fixtures/SyncableMapper.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Fixtures;
+
+/**
+ * Mapper for SyncableModel (extends TestMapper with different model class).
+ */
+class SyncableMapper extends TestMapper
+{
+    public function modelClass(): string
+    {
+        return SyncableModel::class;
+    }
+}

tests/Fixtures/SyncableModel.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Fixtures;
+
+use SocialDept\AtpParity\Concerns\SyncsWithAtp;
+
+/**
+ * Test model with SyncsWithAtp trait for unit testing.
+ *
+ * Extends TestModel so it gets the same mapper from the registry.
+ */
+class SyncableModel extends TestModel
+{
+    use SyncsWithAtp;
+
+    protected $casts = [
+        'atp_synced_at' => 'datetime',
+    ];
+}

tests/Fixtures/TestMapper.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Fixtures;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\RecordMapper;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Test mapper for unit testing.
+ */
+class TestMapper extends RecordMapper
+{
+    public function recordClass(): string
+    {
+        return TestRecord::class;
+    }
+
+    public function modelClass(): string
+    {
+        return TestModel::class;
+    }
+
+    protected function recordToAttributes(Data $record): array
+    {
+        return [
+            'content' => $record->text,
+        ];
+    }
+
+    protected function modelToRecordData(Model $model): array
+    {
+        return [
+            'text' => $model->content,
+            'createdAt' => $model->created_at?->toIso8601String(),
+        ];
+    }
+}

tests/Fixtures/TestModel.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Fixtures;
+
+use Illuminate\Database\Eloquent\Model;
+use SocialDept\AtpParity\Concerns\HasAtpRecord;
+
+/**
+ * Test model for unit testing.
+ */
+class TestModel extends Model
+{
+    use HasAtpRecord;
+
+    protected $table = 'test_models';
+
+    protected $guarded = [];
+
+    protected $casts = [
+        'atp_synced_at' => 'datetime',
+    ];
+}

tests/Fixtures/TestRecord.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Fixtures;
+
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Test record for unit testing.
+ */
+class TestRecord extends Data
+{
+    public function __construct(
+        public readonly string $text,
+        public readonly ?string $createdAt = null,
+    ) {}
+
+    public static function getLexicon(): string
+    {
+        return 'app.test.record';
+    }
+
+    public static function fromArray(array $data): static
+    {
+        return new static(
+            text: $data['text'] ?? '',
+            createdAt: $data['createdAt'] ?? null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return array_filter([
+            'text' => $this->text,
+            'createdAt' => $this->createdAt,
+        ], fn ($v) => $v !== null);
+    }
+}

tests/TestCase.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests;
+
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+use Orchestra\Testbench\TestCase as Orchestra;
+use SocialDept\AtpClient\AtpClientServiceProvider;
+use SocialDept\AtpParity\ParityServiceProvider;
+use SocialDept\AtpResolver\ResolverServiceProvider;
+use SocialDept\AtpSignals\SignalServiceProvider;
+
+abstract class TestCase extends Orchestra
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->setUpDatabase();
+    }
+
+    protected function getPackageProviders($app): array
+    {
+        return [
+            ResolverServiceProvider::class,
+            AtpClientServiceProvider::class,
+            SignalServiceProvider::class,
+            ParityServiceProvider::class,
+        ];
+    }
+
+    protected function getEnvironmentSetUp($app): void
+    {
+        $app['config']->set('database.default', 'testing');
+        $app['config']->set('database.connections.testing', [
+            'driver' => 'sqlite',
+            'database' => ':memory:',
+            'prefix' => '',
+        ]);
+
+        $app['config']->set('parity.columns.uri', 'atp_uri');
+        $app['config']->set('parity.columns.cid', 'atp_cid');
+    }
+
+    protected function setUpDatabase(): void
+    {
+        Schema::create('test_models', function (Blueprint $table) {
+            $table->id();
+            $table->string('content')->nullable();
+            $table->string('did')->nullable();
+            $table->string('atp_uri')->nullable()->unique();
+            $table->string('atp_cid')->nullable();
+            $table->timestamp('atp_synced_at')->nullable();
+            $table->timestamps();
+        });
+
+        Schema::create('parity_import_states', function (Blueprint $table) {
+            $table->id();
+            $table->string('did');
+            $table->string('collection');
+            $table->string('status')->default('pending');
+            $table->integer('records_synced')->default(0);
+            $table->integer('records_skipped')->default(0);
+            $table->integer('records_failed')->default(0);
+            $table->string('cursor')->nullable();
+            $table->text('error')->nullable();
+            $table->timestamp('started_at')->nullable();
+            $table->timestamp('completed_at')->nullable();
+            $table->timestamps();
+
+            $table->unique(['did', 'collection']);
+        });
+
+        Schema::create('parity_conflicts', function (Blueprint $table) {
+            $table->id();
+            $table->morphs('model');
+            $table->string('uri');
+            $table->string('remote_cid');
+            $table->json('remote_data');
+            $table->string('status')->default('pending');
+            $table->timestamp('resolved_at')->nullable();
+            $table->timestamps();
+        });
+    }
+}

tests/Unit/Concerns/HasAtpRecordTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit\Concerns;
+
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpParity\Tests\Fixtures\TestMapper;
+use SocialDept\AtpParity\Tests\Fixtures\TestModel;
+use SocialDept\AtpParity\Tests\Fixtures\TestRecord;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class HasAtpRecordTest extends TestCase
+{
+    public function test_get_atp_uri_returns_uri_from_column(): void
+    {
+        $model = new TestModel(['atp_uri' => 'at://did:plc:test/app.test.record/abc123']);
+
+        $this->assertSame('at://did:plc:test/app.test.record/abc123', $model->getAtpUri());
+    }
+
+    public function test_get_atp_uri_returns_null_when_not_set(): void
+    {
+        $model = new TestModel();
+
+        $this->assertNull($model->getAtpUri());
+    }
+
+    public function test_get_atp_cid_returns_cid_from_column(): void
+    {
+        $model = new TestModel(['atp_cid' => 'bafyreiabc123']);
+
+        $this->assertSame('bafyreiabc123', $model->getAtpCid());
+    }
+
+    public function test_get_atp_cid_returns_null_when_not_set(): void
+    {
+        $model = new TestModel();
+
+        $this->assertNull($model->getAtpCid());
+    }
+
+    public function test_get_atp_did_extracts_did_from_uri(): void
+    {
+        $model = new TestModel(['atp_uri' => 'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/abc123']);
+
+        $this->assertSame('did:plc:z72i7hdynmk6r22z27h6tvur', $model->getAtpDid());
+    }
+
+    public function test_get_atp_did_returns_null_when_no_uri(): void
+    {
+        $model = new TestModel();
+
+        $this->assertNull($model->getAtpDid());
+    }
+
+    public function test_get_atp_did_returns_null_for_malformed_uri(): void
+    {
+        $model = new TestModel(['atp_uri' => 'invalid-uri']);
+
+        $this->assertNull($model->getAtpDid());
+    }
+
+    public function test_get_atp_collection_extracts_collection_from_uri(): void
+    {
+        $model = new TestModel(['atp_uri' => 'at://did:plc:test/app.bsky.feed.post/abc123']);
+
+        $this->assertSame('app.bsky.feed.post', $model->getAtpCollection());
+    }
+
+    public function test_get_atp_collection_returns_null_when_no_uri(): void
+    {
+        $model = new TestModel();
+
+        $this->assertNull($model->getAtpCollection());
+    }
+
+    public function test_get_atp_rkey_extracts_rkey_from_uri(): void
+    {
+        $model = new TestModel(['atp_uri' => 'at://did:plc:test/app.bsky.feed.post/3kj2h4k5j']);
+
+        $this->assertSame('3kj2h4k5j', $model->getAtpRkey());
+    }
+
+    public function test_get_atp_rkey_returns_null_when_no_uri(): void
+    {
+        $model = new TestModel();
+
+        $this->assertNull($model->getAtpRkey());
+    }
+
+    public function test_has_atp_record_returns_true_when_uri_set(): void
+    {
+        $model = new TestModel(['atp_uri' => 'at://did/col/rkey']);
+
+        $this->assertTrue($model->hasAtpRecord());
+    }
+
+    public function test_has_atp_record_returns_false_when_no_uri(): void
+    {
+        $model = new TestModel();
+
+        $this->assertFalse($model->hasAtpRecord());
+    }
+
+    public function test_get_atp_mapper_returns_mapper_when_registered(): void
+    {
+        $registry = app(MapperRegistry::class);
+        $registry->register(new TestMapper());
+
+        $model = new TestModel();
+        $mapper = $model->getAtpMapper();
+
+        $this->assertInstanceOf(TestMapper::class, $mapper);
+    }
+
+    public function test_get_atp_mapper_returns_null_when_not_registered(): void
+    {
+        // Fresh registry without any mappers
+        $this->app->forgetInstance(MapperRegistry::class);
+        $this->app->singleton(MapperRegistry::class);
+
+        $model = new TestModel();
+
+        $this->assertNull($model->getAtpMapper());
+    }
+
+    public function test_to_atp_record_converts_model_to_record(): void
+    {
+        $registry = app(MapperRegistry::class);
+        $registry->register(new TestMapper());
+
+        $model = new TestModel(['content' => 'Hello world']);
+        $record = $model->toAtpRecord();
+
+        $this->assertInstanceOf(TestRecord::class, $record);
+        $this->assertSame('Hello world', $record->text);
+    }
+
+    public function test_to_atp_record_returns_null_when_no_mapper(): void
+    {
+        $this->app->forgetInstance(MapperRegistry::class);
+        $this->app->singleton(MapperRegistry::class);
+
+        $model = new TestModel(['content' => 'Hello']);
+
+        $this->assertNull($model->toAtpRecord());
+    }
+
+    public function test_scope_with_atp_record_filters_synced_models(): void
+    {
+        TestModel::create(['content' => 'Synced', 'atp_uri' => 'at://did/col/rkey1']);
+        TestModel::create(['content' => 'Not synced']);
+        TestModel::create(['content' => 'Also synced', 'atp_uri' => 'at://did/col/rkey2']);
+
+        $synced = TestModel::withAtpRecord()->get();
+
+        $this->assertCount(2, $synced);
+        $this->assertTrue($synced->every(fn ($m) => $m->atp_uri !== null));
+    }
+
+    public function test_scope_without_atp_record_filters_unsynced_models(): void
+    {
+        TestModel::create(['content' => 'Synced', 'atp_uri' => 'at://did/col/rkey']);
+        TestModel::create(['content' => 'Not synced 1']);
+        TestModel::create(['content' => 'Not synced 2']);
+
+        $unsynced = TestModel::withoutAtpRecord()->get();
+
+        $this->assertCount(2, $unsynced);
+        $this->assertTrue($unsynced->every(fn ($m) => $m->atp_uri === null));
+    }
+
+    public function test_scope_where_atp_uri_finds_by_uri(): void
+    {
+        TestModel::create(['content' => 'Target', 'atp_uri' => 'at://did/col/target']);
+        TestModel::create(['content' => 'Other', 'atp_uri' => 'at://did/col/other']);
+
+        $found = TestModel::whereAtpUri('at://did/col/target')->first();
+
+        $this->assertNotNull($found);
+        $this->assertSame('Target', $found->content);
+    }
+
+    public function test_scope_where_atp_uri_returns_null_when_not_found(): void
+    {
+        TestModel::create(['content' => 'Some', 'atp_uri' => 'at://did/col/some']);
+
+        $found = TestModel::whereAtpUri('at://did/col/nonexistent')->first();
+
+        $this->assertNull($found);
+    }
+}

tests/Unit/Concerns/SyncsWithAtpTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit\Concerns;
+
+use Carbon\Carbon;
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpParity\Tests\Fixtures\SyncableMapper;
+use SocialDept\AtpParity\Tests\Fixtures\SyncableModel;
+use SocialDept\AtpParity\Tests\Fixtures\TestRecord;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class SyncsWithAtpTest extends TestCase
+{
+    public function test_get_atp_synced_at_column_returns_default(): void
+    {
+        $model = new SyncableModel();
+
+        $this->assertSame('atp_synced_at', $model->getAtpSyncedAtColumn());
+    }
+
+    public function test_get_atp_synced_at_returns_timestamp(): void
+    {
+        $now = Carbon::now();
+        $model = new SyncableModel(['atp_synced_at' => $now]);
+
+        $this->assertEquals($now->toDateTimeString(), $model->getAtpSyncedAt()->toDateTimeString());
+    }
+
+    public function test_get_atp_synced_at_returns_null_when_not_set(): void
+    {
+        $model = new SyncableModel();
+
+        $this->assertNull($model->getAtpSyncedAt());
+    }
+
+    public function test_mark_as_synced_sets_all_attributes(): void
+    {
+        Carbon::setTestNow('2024-01-15 12:00:00');
+
+        $model = new SyncableModel();
+        $model->markAsSynced('at://did/col/rkey', 'cid123');
+
+        $this->assertSame('at://did/col/rkey', $model->atp_uri);
+        $this->assertSame('cid123', $model->atp_cid);
+        $this->assertSame('2024-01-15 12:00:00', $model->atp_synced_at->toDateTimeString());
+
+        Carbon::setTestNow();
+    }
+
+    public function test_has_local_changes_returns_true_when_never_synced(): void
+    {
+        $model = new SyncableModel();
+
+        $this->assertTrue($model->hasLocalChanges());
+    }
+
+    public function test_has_local_changes_returns_false_when_no_updated_at(): void
+    {
+        $model = new SyncableModel([
+            'atp_synced_at' => Carbon::now(),
+        ]);
+
+        $this->assertFalse($model->hasLocalChanges());
+    }
+
+    public function test_has_local_changes_returns_true_when_updated_after_sync(): void
+    {
+        $model = new SyncableModel([
+            'atp_synced_at' => Carbon::parse('2024-01-15 12:00:00'),
+            'updated_at' => Carbon::parse('2024-01-15 13:00:00'),
+        ]);
+
+        $this->assertTrue($model->hasLocalChanges());
+    }
+
+    public function test_has_local_changes_returns_false_when_synced_after_update(): void
+    {
+        $model = new SyncableModel([
+            'updated_at' => Carbon::parse('2024-01-15 12:00:00'),
+            'atp_synced_at' => Carbon::parse('2024-01-15 13:00:00'),
+        ]);
+
+        $this->assertFalse($model->hasLocalChanges());
+    }
+
+    public function test_update_from_record_updates_model_and_sync_timestamp(): void
+    {
+        Carbon::setTestNow('2024-01-15 14:00:00');
+
+        $registry = app(MapperRegistry::class);
+        $registry->register(new SyncableMapper());
+
+        $model = new SyncableModel(['content' => 'Original']);
+        $record = new TestRecord(text: 'From remote');
+
+        $model->updateFromRecord($record, 'at://did/col/rkey', 'newcid');
+
+        $this->assertSame('From remote', $model->content);
+        $this->assertSame('at://did/col/rkey', $model->atp_uri);
+        $this->assertSame('newcid', $model->atp_cid);
+        $this->assertSame('2024-01-15 14:00:00', $model->atp_synced_at->toDateTimeString());
+
+        Carbon::setTestNow();
+    }
+
+    public function test_update_from_record_does_nothing_without_mapper(): void
+    {
+        $this->app->forgetInstance(MapperRegistry::class);
+        $this->app->singleton(MapperRegistry::class);
+
+        $model = new SyncableModel(['content' => 'Original']);
+        $record = new TestRecord(text: 'From remote');
+
+        $model->updateFromRecord($record, 'at://did/col/rkey', 'cid');
+
+        $this->assertSame('Original', $model->content);
+    }
+
+    public function test_inherits_has_atp_record_methods(): void
+    {
+        $model = new SyncableModel(['atp_uri' => 'at://did:plc:test/app.test.record/rkey']);
+
+        $this->assertTrue($model->hasAtpRecord());
+        $this->assertSame('did:plc:test', $model->getAtpDid());
+        $this->assertSame('app.test.record', $model->getAtpCollection());
+        $this->assertSame('rkey', $model->getAtpRkey());
+    }
+}

tests/Unit/Import/ImportResultTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit\Import;
+
+use SocialDept\AtpParity\Import\ImportResult;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class ImportResultTest extends TestCase
+{
+    public function test_success_creates_completed_result(): void
+    {
+        $result = ImportResult::success(
+            did: 'did:plc:test123',
+            collection: 'app.bsky.feed.post',
+            synced: 50,
+            skipped: 5,
+            failed: 2
+        );
+
+        $this->assertTrue($result->isSuccess());
+        $this->assertFalse($result->isPartial());
+        $this->assertFalse($result->isFailed());
+        $this->assertTrue($result->completed);
+        $this->assertNull($result->error);
+        $this->assertSame(50, $result->recordsSynced);
+        $this->assertSame(5, $result->recordsSkipped);
+        $this->assertSame(2, $result->recordsFailed);
+    }
+
+    public function test_partial_creates_incomplete_result(): void
+    {
+        $result = ImportResult::partial(
+            did: 'did:plc:test123',
+            collection: 'app.bsky.feed.post',
+            synced: 100,
+            cursor: 'abc123'
+        );
+
+        $this->assertFalse($result->isSuccess());
+        $this->assertTrue($result->isPartial());
+        $this->assertFalse($result->isFailed());
+        $this->assertFalse($result->completed);
+        $this->assertSame('abc123', $result->cursor);
+        $this->assertNull($result->error);
+    }
+
+    public function test_failed_creates_error_result(): void
+    {
+        $result = ImportResult::failed(
+            did: 'did:plc:test123',
+            collection: 'app.bsky.feed.post',
+            error: 'Connection failed'
+        );
+
+        $this->assertFalse($result->isSuccess());
+        $this->assertFalse($result->isPartial()); // no records synced
+        $this->assertTrue($result->isFailed());
+        $this->assertSame('Connection failed', $result->error);
+    }
+
+    public function test_failed_with_partial_progress(): void
+    {
+        $result = ImportResult::failed(
+            did: 'did:plc:test123',
+            collection: 'app.bsky.feed.post',
+            error: 'Connection lost',
+            synced: 50,
+            cursor: 'xyz789'
+        );
+
+        $this->assertTrue($result->isFailed());
+        $this->assertTrue($result->isPartial()); // has synced records
+        $this->assertSame(50, $result->recordsSynced);
+        $this->assertSame('xyz789', $result->cursor);
+    }
+
+    public function test_total_processed_sums_all_records(): void
+    {
+        $result = ImportResult::success(
+            did: 'did:plc:test123',
+            collection: 'app.bsky.feed.post',
+            synced: 50,
+            skipped: 10,
+            failed: 5
+        );
+
+        $this->assertSame(65, $result->totalProcessed());
+    }
+
+    public function test_aggregate_combines_multiple_results(): void
+    {
+        $results = [
+            ImportResult::success('did:plc:test', 'app.bsky.feed.post', synced: 50),
+            ImportResult::success('did:plc:test', 'app.bsky.feed.like', synced: 100, failed: 5),
+        ];
+
+        $aggregate = ImportResult::aggregate('did:plc:test', $results);
+
+        $this->assertTrue($aggregate->isSuccess());
+        $this->assertSame('*', $aggregate->collection);
+        $this->assertSame(150, $aggregate->recordsSynced);
+        $this->assertSame(5, $aggregate->recordsFailed);
+        $this->assertNull($aggregate->error);
+    }
+
+    public function test_aggregate_marks_incomplete_when_any_incomplete(): void
+    {
+        $results = [
+            ImportResult::success('did:plc:test', 'app.bsky.feed.post', synced: 50),
+            ImportResult::partial('did:plc:test', 'app.bsky.feed.like', synced: 100, cursor: 'abc'),
+        ];
+
+        $aggregate = ImportResult::aggregate('did:plc:test', $results);
+
+        $this->assertFalse($aggregate->completed);
+    }
+
+    public function test_aggregate_combines_errors(): void
+    {
+        $results = [
+            ImportResult::failed('did:plc:test', 'app.bsky.feed.post', error: 'Error 1'),
+            ImportResult::failed('did:plc:test', 'app.bsky.feed.like', error: 'Error 2'),
+        ];
+
+        $aggregate = ImportResult::aggregate('did:plc:test', $results);
+
+        $this->assertTrue($aggregate->isFailed());
+        $this->assertStringContainsString('app.bsky.feed.post: Error 1', $aggregate->error);
+        $this->assertStringContainsString('app.bsky.feed.like: Error 2', $aggregate->error);
+    }
+
+    public function test_aggregate_with_empty_array(): void
+    {
+        $aggregate = ImportResult::aggregate('did:plc:test', []);
+
+        $this->assertTrue($aggregate->completed);
+        $this->assertSame(0, $aggregate->recordsSynced);
+    }
+}

tests/Unit/Import/ImportServiceTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit\Import;
+
+use Illuminate\Support\Facades\Event;
+use Mockery;
+use SocialDept\AtpParity\Events\ImportCompleted;
+use SocialDept\AtpParity\Events\ImportFailed;
+use SocialDept\AtpParity\Events\ImportProgress;
+use SocialDept\AtpParity\Events\ImportStarted;
+use SocialDept\AtpParity\Import\ImportService;
+use SocialDept\AtpParity\Import\ImportState;
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpParity\Tests\Fixtures\TestMapper;
+use SocialDept\AtpParity\Tests\Fixtures\TestModel;
+use SocialDept\AtpParity\Tests\TestCase;
+use SocialDept\AtpResolver\Facades\Resolver;
+
+class ImportServiceTest extends TestCase
+{
+    private ImportService $service;
+
+    private MapperRegistry $registry;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->registry = new MapperRegistry();
+        $this->registry->register(new TestMapper());
+
+        $this->service = new ImportService($this->registry);
+
+        Event::fake();
+    }
+
+    public function test_import_user_collection_returns_failed_when_no_mapper(): void
+    {
+        $this->app->forgetInstance(MapperRegistry::class);
+        $emptyRegistry = new MapperRegistry();
+        $service = new ImportService($emptyRegistry);
+
+        $result = $service->importUserCollection('did:plc:test', 'unknown.collection');
+
+        $this->assertTrue($result->isFailed());
+        $this->assertStringContainsString('No mapper registered', $result->error);
+    }
+
+    public function test_import_user_collection_fails_when_pds_not_resolved(): void
+    {
+        Resolver::shouldReceive('resolvePds')
+            ->with('did:plc:test')
+            ->andReturnNull();
+
+        $result = $this->service->importUserCollection('did:plc:test', 'app.test.record');
+
+        $this->assertTrue($result->isFailed());
+        $this->assertStringContainsString('Could not resolve PDS', $result->error);
+        Event::assertDispatched(ImportFailed::class);
+    }
+
+    /**
+     * @group integration
+     */
+    public function test_import_user_collection_imports_records(): void
+    {
+        $this->markTestSkipped('Requires integration test with real or mock ATP client - AtpClient has typed properties that prevent mocking');
+    }
+
+    /**
+     * @group integration
+     */
+    public function test_import_dispatches_events(): void
+    {
+        $this->markTestSkipped('Requires integration test with real or mock ATP client - AtpClient has typed properties that prevent mocking');
+    }
+
+    /**
+     * @group integration
+     */
+    public function test_import_calls_progress_callback(): void
+    {
+        $this->markTestSkipped('Requires integration test with real or mock ATP client - AtpClient has typed properties that prevent mocking');
+    }
+
+    /**
+     * @group integration
+     */
+    public function test_import_user_imports_multiple_collections(): void
+    {
+        $this->markTestSkipped('Requires integration test with real or mock ATP client - AtpClient has typed properties that prevent mocking');
+    }
+
+    public function test_get_status_returns_import_state(): void
+    {
+        ImportState::create([
+            'did' => 'did:plc:test',
+            'collection' => 'app.test.record',
+            'status' => 'completed',
+            'records_synced' => 50,
+        ]);
+
+        $state = $this->service->getStatus('did:plc:test', 'app.test.record');
+
+        $this->assertNotNull($state);
+        $this->assertSame('completed', $state->status);
+        $this->assertSame(50, $state->records_synced);
+    }
+
+    public function test_get_status_returns_null_when_not_found(): void
+    {
+        $state = $this->service->getStatus('did:plc:unknown', 'unknown');
+
+        $this->assertNull($state);
+    }
+
+    public function test_is_imported_returns_true_when_completed(): void
+    {
+        ImportState::create([
+            'did' => 'did:plc:test',
+            'collection' => 'app.test.record',
+            'status' => 'completed',
+        ]);
+
+        $this->assertTrue($this->service->isImported('did:plc:test', 'app.test.record'));
+    }
+
+    public function test_is_imported_returns_false_when_not_started(): void
+    {
+        $this->assertFalse($this->service->isImported('did:plc:test', 'app.test.record'));
+    }
+
+    public function test_reset_deletes_import_state(): void
+    {
+        ImportState::create([
+            'did' => 'did:plc:test',
+            'collection' => 'app.test.record',
+            'status' => 'completed',
+        ]);
+
+        $this->service->reset('did:plc:test', 'app.test.record');
+
+        $this->assertNull($this->service->getStatus('did:plc:test', 'app.test.record'));
+    }
+
+    public function test_import_skips_already_completed(): void
+    {
+        ImportState::create([
+            'did' => 'did:plc:test',
+            'collection' => 'app.test.record',
+            'status' => 'completed',
+            'records_synced' => 100,
+        ]);
+
+        // No mocking needed - should return cached result
+        $result = $this->service->importUserCollection('did:plc:test', 'app.test.record');
+
+        $this->assertTrue($result->completed);
+        $this->assertSame(100, $result->recordsSynced);
+    }
+
+    /**
+     * @group integration
+     */
+    public function test_import_handles_record_failures_gracefully(): void
+    {
+        $this->markTestSkipped('Requires integration test with real or mock ATP client - AtpClient has typed properties that prevent mocking');
+    }
+}

tests/Unit/MapperRegistryTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit;
+
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpParity\Tests\Fixtures\TestMapper;
+use SocialDept\AtpParity\Tests\Fixtures\TestModel;
+use SocialDept\AtpParity\Tests\Fixtures\TestRecord;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class MapperRegistryTest extends TestCase
+{
+    private MapperRegistry $registry;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->registry = new MapperRegistry();
+    }
+
+    public function test_register_adds_mapper_to_all_indices(): void
+    {
+        $mapper = new TestMapper();
+
+        $this->registry->register($mapper);
+
+        $this->assertSame($mapper, $this->registry->forRecord(TestRecord::class));
+        $this->assertSame($mapper, $this->registry->forModel(TestModel::class));
+        $this->assertSame($mapper, $this->registry->forLexicon('app.test.record'));
+    }
+
+    public function test_for_record_returns_null_for_unregistered_class(): void
+    {
+        $result = $this->registry->forRecord('NonExistent\\Record');
+
+        $this->assertNull($result);
+    }
+
+    public function test_for_model_returns_null_for_unregistered_class(): void
+    {
+        $result = $this->registry->forModel('NonExistent\\Model');
+
+        $this->assertNull($result);
+    }
+
+    public function test_for_lexicon_returns_null_for_unregistered_nsid(): void
+    {
+        $result = $this->registry->forLexicon('app.unknown.record');
+
+        $this->assertNull($result);
+    }
+
+    public function test_has_lexicon_returns_true_when_registered(): void
+    {
+        $this->registry->register(new TestMapper());
+
+        $this->assertTrue($this->registry->hasLexicon('app.test.record'));
+    }
+
+    public function test_has_lexicon_returns_false_when_not_registered(): void
+    {
+        $this->assertFalse($this->registry->hasLexicon('app.unknown.record'));
+    }
+
+    public function test_lexicons_returns_all_registered_nsids(): void
+    {
+        $this->registry->register(new TestMapper());
+
+        $lexicons = $this->registry->lexicons();
+
+        $this->assertContains('app.test.record', $lexicons);
+        $this->assertCount(1, $lexicons);
+    }
+
+    public function test_lexicons_returns_empty_array_when_no_mappers_registered(): void
+    {
+        $this->assertEmpty($this->registry->lexicons());
+    }
+
+    public function test_all_returns_all_registered_mappers(): void
+    {
+        $mapper = new TestMapper();
+        $this->registry->register($mapper);
+
+        $all = $this->registry->all();
+
+        $this->assertCount(1, $all);
+        $this->assertSame($mapper, $all[0]);
+    }
+
+    public function test_all_returns_empty_array_when_no_mappers_registered(): void
+    {
+        $this->assertEmpty($this->registry->all());
+    }
+
+    public function test_registering_same_mapper_twice_overwrites(): void
+    {
+        $mapper1 = new TestMapper();
+        $mapper2 = new TestMapper();
+
+        $this->registry->register($mapper1);
+        $this->registry->register($mapper2);
+
+        $this->assertSame($mapper2, $this->registry->forRecord(TestRecord::class));
+        $this->assertCount(1, $this->registry->all());
+    }
+}

tests/Unit/Publish/PublishResultTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit\Publish;
+
+use SocialDept\AtpParity\Publish\PublishResult;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class PublishResultTest extends TestCase
+{
+    public function test_success_creates_successful_result(): void
+    {
+        $result = PublishResult::success(
+            uri: 'at://did:plc:test/app.bsky.feed.post/abc123',
+            cid: 'bafyreiabc123'
+        );
+
+        $this->assertTrue($result->isSuccess());
+        $this->assertFalse($result->isFailed());
+        $this->assertSame('at://did:plc:test/app.bsky.feed.post/abc123', $result->uri);
+        $this->assertSame('bafyreiabc123', $result->cid);
+        $this->assertNull($result->error);
+    }
+
+    public function test_failed_creates_failed_result(): void
+    {
+        $result = PublishResult::failed('Authentication required');
+
+        $this->assertFalse($result->isSuccess());
+        $this->assertTrue($result->isFailed());
+        $this->assertNull($result->uri);
+        $this->assertNull($result->cid);
+        $this->assertSame('Authentication required', $result->error);
+    }
+
+    public function test_is_success_returns_correct_boolean(): void
+    {
+        $success = new PublishResult(success: true);
+        $failure = new PublishResult(success: false);
+
+        $this->assertTrue($success->isSuccess());
+        $this->assertFalse($failure->isSuccess());
+    }
+
+    public function test_is_failed_returns_correct_boolean(): void
+    {
+        $success = new PublishResult(success: true);
+        $failure = new PublishResult(success: false);
+
+        $this->assertFalse($success->isFailed());
+        $this->assertTrue($failure->isFailed());
+    }
+
+    public function test_success_result_properties_are_accessible(): void
+    {
+        $result = PublishResult::success('at://did/col/rkey', 'cid123');
+
+        $this->assertTrue($result->success);
+        $this->assertSame('at://did/col/rkey', $result->uri);
+        $this->assertSame('cid123', $result->cid);
+    }
+
+    public function test_failed_result_error_is_accessible(): void
+    {
+        $result = PublishResult::failed('Something went wrong');
+
+        $this->assertFalse($result->success);
+        $this->assertSame('Something went wrong', $result->error);
+    }
+}

tests/Unit/Publish/PublishServiceTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit\Publish;
+
+use Illuminate\Support\Facades\Event;
+use Mockery;
+use SocialDept\AtpParity\Events\RecordPublished;
+use SocialDept\AtpParity\Events\RecordUnpublished;
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpParity\Publish\PublishService;
+use SocialDept\AtpParity\Tests\Fixtures\TestMapper;
+use SocialDept\AtpParity\Tests\Fixtures\TestModel;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class PublishServiceTest extends TestCase
+{
+    private PublishService $service;
+
+    private MapperRegistry $registry;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->registry = new MapperRegistry();
+        $this->registry->register(new TestMapper());
+
+        $this->service = new PublishService($this->registry);
+
+        Event::fake();
+    }
+
+    public function test_publish_fails_when_no_did_available(): void
+    {
+        $model = new TestModel(['content' => 'Test']);
+
+        $result = $this->service->publish($model);
+
+        $this->assertTrue($result->isFailed());
+        $this->assertStringContainsString('No DID', $result->error);
+    }
+
+    public function test_publish_uses_did_from_model_column(): void
+    {
+        $model = new TestModel([
+            'content' => 'Test',
+            'did' => 'did:plc:test123',
+        ]);
+
+        $this->mockAtpClient('did:plc:test123', 'at://did:plc:test123/app.test.record/abc', 'cid123');
+
+        $result = $this->service->publish($model);
+
+        $this->assertTrue($result->isSuccess());
+        $this->assertSame('at://did:plc:test123/app.test.record/abc', $result->uri);
+    }
+
+    public function test_publish_as_creates_record_with_specified_did(): void
+    {
+        $model = new TestModel(['content' => 'Hello world']);
+
+        $this->mockAtpClient('did:plc:specified', 'at://did:plc:specified/app.test.record/xyz', 'newcid');
+
+        $result = $this->service->publishAs('did:plc:specified', $model);
+
+        $this->assertTrue($result->isSuccess());
+        $this->assertSame('at://did:plc:specified/app.test.record/xyz', $result->uri);
+        $this->assertSame('newcid', $result->cid);
+    }
+
+    public function test_publish_as_updates_model_metadata(): void
+    {
+        $model = TestModel::create(['content' => 'Test']);
+
+        $this->mockAtpClient('did:plc:test', 'at://did:plc:test/app.test.record/rkey', 'cid');
+
+        $this->service->publishAs('did:plc:test', $model);
+
+        $model->refresh();
+        $this->assertSame('at://did:plc:test/app.test.record/rkey', $model->atp_uri);
+        $this->assertSame('cid', $model->atp_cid);
+    }
+
+    public function test_publish_dispatches_record_published_event(): void
+    {
+        $model = new TestModel(['content' => 'Test', 'did' => 'did:plc:test']);
+
+        $this->mockAtpClient('did:plc:test', 'at://did/col/rkey', 'cid');
+
+        $this->service->publish($model);
+
+        Event::assertDispatched(RecordPublished::class);
+    }
+
+    public function test_publish_redirects_to_update_when_already_published(): void
+    {
+        $model = TestModel::create([
+            'content' => 'Existing',
+            'atp_uri' => 'at://did:plc:test/app.test.record/existing',
+            'atp_cid' => 'oldcid',
+        ]);
+
+        $this->mockAtpClientForUpdate('did:plc:test', 'at://did:plc:test/app.test.record/existing', 'newcid');
+
+        $result = $this->service->publishAs('did:plc:test', $model);
+
+        $this->assertTrue($result->isSuccess());
+    }
+
+    public function test_update_fails_when_not_published(): void
+    {
+        $model = new TestModel(['content' => 'Not published']);
+
+        $result = $this->service->update($model);
+
+        $this->assertTrue($result->isFailed());
+        $this->assertStringContainsString('not been published', $result->error);
+    }
+
+    public function test_update_calls_put_record(): void
+    {
+        $model = TestModel::create([
+            'content' => 'Updated content',
+            'atp_uri' => 'at://did:plc:test/app.test.record/rkey123',
+            'atp_cid' => 'oldcid',
+        ]);
+
+        $this->mockAtpClientForUpdate('did:plc:test', 'at://did:plc:test/app.test.record/rkey123', 'updatedcid');
+
+        $result = $this->service->update($model);
+
+        $this->assertTrue($result->isSuccess());
+        $this->assertSame('updatedcid', $result->cid);
+    }
+
+    public function test_delete_removes_record_and_clears_metadata(): void
+    {
+        $model = TestModel::create([
+            'content' => 'To delete',
+            'atp_uri' => 'at://did:plc:test/app.test.record/todelete',
+            'atp_cid' => 'cid',
+        ]);
+
+        $this->mockAtpClientForDelete('did:plc:test');
+
+        $result = $this->service->delete($model);
+
+        $this->assertTrue($result);
+
+        $model->refresh();
+        $this->assertNull($model->atp_uri);
+        $this->assertNull($model->atp_cid);
+    }
+
+    public function test_delete_dispatches_record_unpublished_event(): void
+    {
+        $model = TestModel::create([
+            'content' => 'To delete',
+            'atp_uri' => 'at://did:plc:test/app.test.record/xyz',
+            'atp_cid' => 'cid',
+        ]);
+
+        $this->mockAtpClientForDelete('did:plc:test');
+
+        $this->service->delete($model);
+
+        Event::assertDispatched(RecordUnpublished::class);
+    }
+
+    public function test_delete_returns_false_when_not_published(): void
+    {
+        $model = new TestModel(['content' => 'Not published']);
+
+        $result = $this->service->delete($model);
+
+        $this->assertFalse($result);
+    }
+
+    public function test_publish_handles_exception_gracefully(): void
+    {
+        $model = new TestModel(['content' => 'Test', 'did' => 'did:plc:test']);
+
+        $this->mockAtpClientWithException('did:plc:test', 'API error occurred');
+
+        $result = $this->service->publish($model);
+
+        $this->assertTrue($result->isFailed());
+        $this->assertSame('API error occurred', $result->error);
+    }
+
+    public function test_update_fails_for_invalid_uri(): void
+    {
+        $model = new TestModel([
+            'content' => 'Test',
+            'atp_uri' => 'invalid-uri-format',
+        ]);
+
+        $result = $this->service->update($model);
+
+        $this->assertTrue($result->isFailed());
+        $this->assertStringContainsString('Invalid AT Protocol URI', $result->error);
+    }
+
+    /**
+     * Mock AtpClient for create operations.
+     */
+    protected function mockAtpClient(string $did, string $returnUri, string $returnCid): void
+    {
+        $response = new \stdClass();
+        $response->uri = $returnUri;
+        $response->cid = $returnCid;
+
+        $repoClient = Mockery::mock();
+        $repoClient->shouldReceive('createRecord')
+            ->andReturn($response);
+
+        // Create client mock with property chain (no typed properties)
+        $atprotoClient = Mockery::mock();
+        $atprotoClient->repo = $repoClient;
+
+        $atpClient = Mockery::mock();
+        $atpClient->atproto = $atprotoClient;
+
+        // Bind a manager mock to the container
+        $manager = Mockery::mock();
+        $manager->shouldReceive('as')
+            ->with($did)
+            ->andReturn($atpClient);
+
+        $this->app->instance('atp-client', $manager);
+    }
+
+    /**
+     * Mock AtpClient for update operations.
+     */
+    protected function mockAtpClientForUpdate(string $did, string $returnUri, string $returnCid): void
+    {
+        $response = new \stdClass();
+        $response->uri = $returnUri;
+        $response->cid = $returnCid;
+
+        $repoClient = Mockery::mock();
+        $repoClient->shouldReceive('putRecord')
+            ->andReturn($response);
+
+        // Create client mock with property chain (no typed properties)
+        $atprotoClient = Mockery::mock();
+        $atprotoClient->repo = $repoClient;
+
+        $atpClient = Mockery::mock();
+        $atpClient->atproto = $atprotoClient;
+
+        // Bind a manager mock to the container
+        $manager = Mockery::mock();
+        $manager->shouldReceive('as')
+            ->with($did)
+            ->andReturn($atpClient);
+
+        $this->app->instance('atp-client', $manager);
+    }
+
+    /**
+     * Mock AtpClient for delete operations.
+     */
+    protected function mockAtpClientForDelete(string $did): void
+    {
+        $repoClient = Mockery::mock();
+        $repoClient->shouldReceive('deleteRecord')
+            ->andReturnNull();
+
+        // Create client mock with property chain (no typed properties)
+        $atprotoClient = Mockery::mock();
+        $atprotoClient->repo = $repoClient;
+
+        $atpClient = Mockery::mock();
+        $atpClient->atproto = $atprotoClient;
+
+        // Bind a manager mock to the container
+        $manager = Mockery::mock();
+        $manager->shouldReceive('as')
+            ->with($did)
+            ->andReturn($atpClient);
+
+        $this->app->instance('atp-client', $manager);
+    }
+
+    /**
+     * Mock AtpClient to throw exception.
+     */
+    protected function mockAtpClientWithException(string $did, string $message): void
+    {
+        $manager = Mockery::mock();
+        $manager->shouldReceive('as')
+            ->with($did)
+            ->andThrow(new \Exception($message));
+
+        $this->app->instance('atp-client', $manager);
+    }
+}

tests/Unit/RecordMapperTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit;
+
+use SocialDept\AtpParity\Tests\Fixtures\TestMapper;
+use SocialDept\AtpParity\Tests\Fixtures\TestModel;
+use SocialDept\AtpParity\Tests\Fixtures\TestRecord;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class RecordMapperTest extends TestCase
+{
+    private TestMapper $mapper;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->mapper = new TestMapper();
+    }
+
+    public function test_record_class_returns_correct_class(): void
+    {
+        $this->assertSame(TestRecord::class, $this->mapper->recordClass());
+    }
+
+    public function test_model_class_returns_correct_class(): void
+    {
+        $this->assertSame(TestModel::class, $this->mapper->modelClass());
+    }
+
+    public function test_lexicon_returns_record_lexicon(): void
+    {
+        $this->assertSame('app.test.record', $this->mapper->lexicon());
+    }
+
+    public function test_to_model_creates_model_with_attributes(): void
+    {
+        $record = new TestRecord(text: 'Hello world');
+
+        $model = $this->mapper->toModel($record);
+
+        $this->assertInstanceOf(TestModel::class, $model);
+        $this->assertSame('Hello world', $model->content);
+        $this->assertFalse($model->exists);
+    }
+
+    public function test_to_model_applies_meta(): void
+    {
+        $record = new TestRecord(text: 'Test');
+        $meta = [
+            'uri' => 'at://did:plc:test/app.test.record/abc123',
+            'cid' => 'bafyreiabc',
+        ];
+
+        $model = $this->mapper->toModel($record, $meta);
+
+        $this->assertSame('at://did:plc:test/app.test.record/abc123', $model->atp_uri);
+        $this->assertSame('bafyreiabc', $model->atp_cid);
+    }
+
+    public function test_to_record_converts_model_to_record(): void
+    {
+        $model = new TestModel(['content' => 'Test content']);
+
+        $record = $this->mapper->toRecord($model);
+
+        $this->assertInstanceOf(TestRecord::class, $record);
+        $this->assertSame('Test content', $record->text);
+    }
+
+    public function test_update_model_fills_model_without_saving(): void
+    {
+        $model = new TestModel(['content' => 'Original']);
+        $model->save();
+        $originalUpdatedAt = $model->updated_at;
+
+        $record = new TestRecord(text: 'Updated');
+
+        $result = $this->mapper->updateModel($model, $record);
+
+        $this->assertSame($model, $result);
+        $this->assertSame('Updated', $model->content);
+        // Model is filled but not saved
+        $this->assertTrue($model->isDirty('content'));
+    }
+
+    public function test_update_model_applies_meta(): void
+    {
+        $model = new TestModel(['content' => 'Original']);
+        $record = new TestRecord(text: 'Updated');
+        $meta = ['uri' => 'at://test/col/rkey', 'cid' => 'cid123'];
+
+        $this->mapper->updateModel($model, $record, $meta);
+
+        $this->assertSame('at://test/col/rkey', $model->atp_uri);
+        $this->assertSame('cid123', $model->atp_cid);
+    }
+
+    public function test_find_by_uri_returns_model_when_exists(): void
+    {
+        $model = TestModel::create([
+            'content' => 'Test',
+            'atp_uri' => 'at://did:plc:test/app.test.record/abc',
+        ]);
+
+        $found = $this->mapper->findByUri('at://did:plc:test/app.test.record/abc');
+
+        $this->assertNotNull($found);
+        $this->assertSame($model->id, $found->id);
+    }
+
+    public function test_find_by_uri_returns_null_when_not_exists(): void
+    {
+        $found = $this->mapper->findByUri('at://nonexistent/col/rkey');
+
+        $this->assertNull($found);
+    }
+
+    public function test_upsert_creates_new_model_when_uri_not_found(): void
+    {
+        $record = new TestRecord(text: 'New record');
+        $meta = [
+            'uri' => 'at://did:plc:test/app.test.record/new123',
+            'cid' => 'bafyrei123',
+        ];
+
+        $model = $this->mapper->upsert($record, $meta);
+
+        $this->assertTrue($model->exists);
+        $this->assertSame('New record', $model->content);
+        $this->assertSame('at://did:plc:test/app.test.record/new123', $model->atp_uri);
+    }
+
+    public function test_upsert_updates_existing_model_when_uri_found(): void
+    {
+        $existing = TestModel::create([
+            'content' => 'Original',
+            'atp_uri' => 'at://did:plc:test/app.test.record/exists',
+            'atp_cid' => 'old_cid',
+        ]);
+
+        $record = new TestRecord(text: 'Updated content');
+        $meta = [
+            'uri' => 'at://did:plc:test/app.test.record/exists',
+            'cid' => 'new_cid',
+        ];
+
+        $model = $this->mapper->upsert($record, $meta);
+
+        $this->assertSame($existing->id, $model->id);
+        $this->assertSame('Updated content', $model->content);
+        $this->assertSame('new_cid', $model->atp_cid);
+    }
+
+    public function test_upsert_without_uri_creates_new_model(): void
+    {
+        $record = new TestRecord(text: 'No URI');
+
+        $model = $this->mapper->upsert($record, []);
+
+        $this->assertTrue($model->exists);
+        $this->assertSame('No URI', $model->content);
+        $this->assertNull($model->atp_uri);
+    }
+
+    public function test_delete_by_uri_deletes_model_when_exists(): void
+    {
+        TestModel::create([
+            'content' => 'To delete',
+            'atp_uri' => 'at://did:plc:test/app.test.record/todelete',
+        ]);
+
+        $result = $this->mapper->deleteByUri('at://did:plc:test/app.test.record/todelete');
+
+        $this->assertTrue($result);
+        $this->assertNull($this->mapper->findByUri('at://did:plc:test/app.test.record/todelete'));
+    }
+
+    public function test_delete_by_uri_returns_false_when_not_exists(): void
+    {
+        $result = $this->mapper->deleteByUri('at://nonexistent/col/rkey');
+
+        $this->assertFalse($result);
+    }
+}

tests/Unit/SchemaMapperTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit;
+
+use SocialDept\AtpParity\Support\SchemaMapper;
+use SocialDept\AtpParity\Tests\Fixtures\TestModel;
+use SocialDept\AtpParity\Tests\Fixtures\TestRecord;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class SchemaMapperTest extends TestCase
+{
+    public function test_record_class_returns_schema_class(): void
+    {
+        $mapper = new SchemaMapper(
+            schemaClass: TestRecord::class,
+            modelClass: TestModel::class,
+            toAttributes: fn () => [],
+            toRecordData: fn () => [],
+        );
+
+        $this->assertSame(TestRecord::class, $mapper->recordClass());
+    }
+
+    public function test_model_class_returns_model_class(): void
+    {
+        $mapper = new SchemaMapper(
+            schemaClass: TestRecord::class,
+            modelClass: TestModel::class,
+            toAttributes: fn () => [],
+            toRecordData: fn () => [],
+        );
+
+        $this->assertSame(TestModel::class, $mapper->modelClass());
+    }
+
+    public function test_lexicon_returns_schema_lexicon(): void
+    {
+        $mapper = new SchemaMapper(
+            schemaClass: TestRecord::class,
+            modelClass: TestModel::class,
+            toAttributes: fn () => [],
+            toRecordData: fn () => [],
+        );
+
+        $this->assertSame('app.test.record', $mapper->lexicon());
+    }
+
+    public function test_to_model_invokes_to_attributes_closure(): void
+    {
+        $closureCalled = false;
+
+        $mapper = new SchemaMapper(
+            schemaClass: TestRecord::class,
+            modelClass: TestModel::class,
+            toAttributes: function (TestRecord $record) use (&$closureCalled) {
+                $closureCalled = true;
+
+                return ['content' => $record->text.'_transformed'];
+            },
+            toRecordData: fn () => [],
+        );
+
+        $record = new TestRecord(text: 'original');
+        $model = $mapper->toModel($record);
+
+        $this->assertTrue($closureCalled);
+        $this->assertSame('original_transformed', $model->content);
+    }
+
+    public function test_to_record_invokes_to_record_data_closure(): void
+    {
+        $closureCalled = false;
+
+        $mapper = new SchemaMapper(
+            schemaClass: TestRecord::class,
+            modelClass: TestModel::class,
+            toAttributes: fn () => [],
+            toRecordData: function (TestModel $model) use (&$closureCalled) {
+                $closureCalled = true;
+
+                return ['text' => strtoupper($model->content)];
+            },
+        );
+
+        $model = new TestModel(['content' => 'hello']);
+        $record = $mapper->toRecord($model);
+
+        $this->assertTrue($closureCalled);
+        $this->assertSame('HELLO', $record->text);
+    }
+
+    public function test_closures_receive_correct_types(): void
+    {
+        $receivedRecordType = null;
+        $receivedModelType = null;
+
+        $mapper = new SchemaMapper(
+            schemaClass: TestRecord::class,
+            modelClass: TestModel::class,
+            toAttributes: function ($record) use (&$receivedRecordType) {
+                $receivedRecordType = get_class($record);
+
+                return ['content' => $record->text];
+            },
+            toRecordData: function ($model) use (&$receivedModelType) {
+                $receivedModelType = get_class($model);
+
+                return ['text' => $model->content];
+            },
+        );
+
+        $mapper->toModel(new TestRecord(text: 'test'));
+        $mapper->toRecord(new TestModel(['content' => 'test']));
+
+        $this->assertSame(TestRecord::class, $receivedRecordType);
+        $this->assertSame(TestModel::class, $receivedModelType);
+    }
+
+    public function test_upsert_works_with_schema_mapper(): void
+    {
+        $mapper = new SchemaMapper(
+            schemaClass: TestRecord::class,
+            modelClass: TestModel::class,
+            toAttributes: fn (TestRecord $r) => ['content' => $r->text],
+            toRecordData: fn (TestModel $m) => ['text' => $m->content],
+        );
+
+        $record = new TestRecord(text: 'schema mapper test');
+        $meta = ['uri' => 'at://test/col/rkey', 'cid' => 'cid123'];
+
+        $model = $mapper->upsert($record, $meta);
+
+        $this->assertTrue($model->exists);
+        $this->assertSame('schema mapper test', $model->content);
+        $this->assertSame('at://test/col/rkey', $model->atp_uri);
+    }
+}

tests/Unit/Sync/ConflictDetectorTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit\Sync;
+
+use Carbon\Carbon;
+use SocialDept\AtpParity\Sync\ConflictDetector;
+use SocialDept\AtpParity\Tests\Fixtures\SyncableModel;
+use SocialDept\AtpParity\Tests\Fixtures\TestModel;
+use SocialDept\AtpParity\Tests\Fixtures\TestRecord;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class ConflictDetectorTest extends TestCase
+{
+    private ConflictDetector $detector;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->detector = new ConflictDetector();
+    }
+
+    public function test_no_conflict_when_cid_matches(): void
+    {
+        $model = new TestModel([
+            'atp_cid' => 'samecid123',
+            'atp_synced_at' => Carbon::parse('2024-01-15 12:00:00'),
+            'updated_at' => Carbon::parse('2024-01-15 13:00:00'), // local changes
+        ]);
+        $record = new TestRecord(text: 'Remote content');
+
+        $hasConflict = $this->detector->hasConflict($model, $record, 'samecid123');
+
+        $this->assertFalse($hasConflict);
+    }
+
+    public function test_no_conflict_when_no_local_changes(): void
+    {
+        $model = new TestModel([
+            'atp_cid' => 'oldcid',
+            'atp_synced_at' => Carbon::parse('2024-01-15 13:00:00'),
+            'updated_at' => Carbon::parse('2024-01-15 12:00:00'), // updated before sync
+        ]);
+        $record = new TestRecord(text: 'Remote content');
+
+        $hasConflict = $this->detector->hasConflict($model, $record, 'newcid');
+
+        $this->assertFalse($hasConflict);
+    }
+
+    public function test_conflict_when_cid_differs_and_local_changes(): void
+    {
+        $model = new TestModel([
+            'atp_cid' => 'oldcid',
+            'atp_synced_at' => Carbon::parse('2024-01-15 12:00:00'),
+            'updated_at' => Carbon::parse('2024-01-15 13:00:00'), // local changes
+        ]);
+        $record = new TestRecord(text: 'Remote content');
+
+        $hasConflict = $this->detector->hasConflict($model, $record, 'newcid');
+
+        $this->assertTrue($hasConflict);
+    }
+
+    public function test_conflict_when_never_synced(): void
+    {
+        $model = new TestModel([
+            'atp_cid' => 'cid',
+            // No atp_synced_at means never synced, which implies local changes
+        ]);
+        $record = new TestRecord(text: 'Remote');
+
+        $hasConflict = $this->detector->hasConflict($model, $record, 'differentcid');
+
+        $this->assertTrue($hasConflict);
+    }
+
+    public function test_uses_syncs_with_atp_trait_method(): void
+    {
+        $model = new SyncableModel([
+            'atp_cid' => 'oldcid',
+            'atp_synced_at' => Carbon::parse('2024-01-15 12:00:00'),
+            'updated_at' => Carbon::parse('2024-01-15 13:00:00'),
+        ]);
+        $record = new TestRecord(text: 'Remote');
+
+        $hasConflict = $this->detector->hasConflict($model, $record, 'newcid');
+
+        $this->assertTrue($hasConflict);
+    }
+
+    public function test_no_conflict_when_synced_after_update_with_trait(): void
+    {
+        $model = new SyncableModel([
+            'atp_cid' => 'oldcid',
+            'updated_at' => Carbon::parse('2024-01-15 12:00:00'),
+            'atp_synced_at' => Carbon::parse('2024-01-15 13:00:00'),
+        ]);
+        $record = new TestRecord(text: 'Remote');
+
+        $hasConflict = $this->detector->hasConflict($model, $record, 'newcid');
+
+        $this->assertFalse($hasConflict);
+    }
+
+    public function test_no_conflict_without_updated_at(): void
+    {
+        $model = new TestModel([
+            'atp_cid' => 'cid',
+            'atp_synced_at' => Carbon::now(),
+            // No updated_at
+        ]);
+        $record = new TestRecord(text: 'Remote');
+
+        $hasConflict = $this->detector->hasConflict($model, $record, 'newcid');
+
+        $this->assertFalse($hasConflict);
+    }
+}

tests/Unit/Sync/ConflictResolutionTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit\Sync;
+
+use SocialDept\AtpParity\Sync\ConflictResolution;
+use SocialDept\AtpParity\Sync\PendingConflict;
+use SocialDept\AtpParity\Tests\Fixtures\TestModel;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class ConflictResolutionTest extends TestCase
+{
+    public function test_remote_wins_creates_resolved_resolution(): void
+    {
+        $model = new TestModel();
+
+        $resolution = ConflictResolution::remoteWins($model);
+
+        $this->assertTrue($resolution->isResolved());
+        $this->assertFalse($resolution->isPending());
+        $this->assertSame('remote', $resolution->winner);
+        $this->assertSame($model, $resolution->model);
+        $this->assertNull($resolution->pending);
+    }
+
+    public function test_local_wins_creates_resolved_resolution(): void
+    {
+        $model = new TestModel();
+
+        $resolution = ConflictResolution::localWins($model);
+
+        $this->assertTrue($resolution->isResolved());
+        $this->assertFalse($resolution->isPending());
+        $this->assertSame('local', $resolution->winner);
+        $this->assertSame($model, $resolution->model);
+        $this->assertNull($resolution->pending);
+    }
+
+    public function test_pending_creates_unresolved_resolution(): void
+    {
+        $pending = new PendingConflict();
+
+        $resolution = ConflictResolution::pending($pending);
+
+        $this->assertFalse($resolution->isResolved());
+        $this->assertTrue($resolution->isPending());
+        $this->assertSame('manual', $resolution->winner);
+        $this->assertNull($resolution->model);
+        $this->assertSame($pending, $resolution->pending);
+    }
+
+    public function test_is_resolved_returns_correct_boolean(): void
+    {
+        $resolved = new ConflictResolution(resolved: true, winner: 'remote');
+        $unresolved = new ConflictResolution(resolved: false, winner: 'manual');
+
+        $this->assertTrue($resolved->isResolved());
+        $this->assertFalse($unresolved->isResolved());
+    }
+
+    public function test_is_pending_returns_false_when_no_pending_conflict(): void
+    {
+        $resolution = new ConflictResolution(resolved: false, winner: 'manual');
+
+        $this->assertFalse($resolution->isPending());
+    }
+}

tests/Unit/Sync/ConflictStrategyTest.php

···
+<?php
+
+namespace SocialDept\AtpParity\Tests\Unit\Sync;
+
+use SocialDept\AtpParity\Sync\ConflictStrategy;
+use SocialDept\AtpParity\Tests\TestCase;
+
+class ConflictStrategyTest extends TestCase
+{
+    public function test_remote_wins_has_correct_value(): void
+    {
+        $this->assertSame('remote', ConflictStrategy::RemoteWins->value);
+    }
+
+    public function test_local_wins_has_correct_value(): void
+    {
+        $this->assertSame('local', ConflictStrategy::LocalWins->value);
+    }
+
+    public function test_newest_wins_has_correct_value(): void
+    {
+        $this->assertSame('newest', ConflictStrategy::NewestWins->value);
+    }
+
+    public function test_manual_has_correct_value(): void
+    {
+        $this->assertSame('manual', ConflictStrategy::Manual->value);
+    }
+
+    public function test_from_config_returns_remote_wins_by_default(): void
+    {
+        config()->set('parity.conflicts.strategy', 'remote');
+
+        $strategy = ConflictStrategy::fromConfig();
+
+        $this->assertSame(ConflictStrategy::RemoteWins, $strategy);
+    }
+
+    public function test_from_config_returns_local_wins(): void
+    {
+        config()->set('parity.conflicts.strategy', 'local');
+
+        $strategy = ConflictStrategy::fromConfig();
+
+        $this->assertSame(ConflictStrategy::LocalWins, $strategy);
+    }
+
+    public function test_from_config_returns_newest_wins(): void
+    {
+        config()->set('parity.conflicts.strategy', 'newest');
+
+        $strategy = ConflictStrategy::fromConfig();
+
+        $this->assertSame(ConflictStrategy::NewestWins, $strategy);
+    }
+
+    public function test_from_config_returns_manual(): void
+    {
+        config()->set('parity.conflicts.strategy', 'manual');
+
+        $strategy = ConflictStrategy::fromConfig();
+
+        $this->assertSame(ConflictStrategy::Manual, $strategy);
+    }
+
+    public function test_from_config_defaults_to_remote_wins_for_invalid_value(): void
+    {
+        config()->set('parity.conflicts.strategy', 'invalid');
+
+        $strategy = ConflictStrategy::fromConfig();
+
+        $this->assertSame(ConflictStrategy::RemoteWins, $strategy);
+    }
+
+    public function test_from_config_defaults_to_remote_wins_when_not_set(): void
+    {
+        config()->set('parity.conflicts.strategy', null);
+
+        $strategy = ConflictStrategy::fromConfig();
+
+        $this->assertSame(ConflictStrategy::RemoteWins, $strategy);
+    }
+}