Add reported and discovered datetime fields to release output

Add a nullable `reported` timestamp column to package_releases for
author-declared release dates. Expose both `reported` and `discovered`
(mapped from created_at) as ISO 8601 strings in the FAIR metadata
response. Includes migration, model cast, factory update, and tests.

Closes fairpm/fair-protocol#64

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Joost de Valk <joost@altha.nl>

Author: jdevalk

app/Models/PackageRelease.php

@@ -20,6 +20,7 @@
  * @property-read array<string, mixed>|null     $artifacts
  * @property-read string|null                   $signature
  * @property-read string|null                   $checksum
+ * @property-read CarbonImmutable|null          $reported
  * @property-read CarbonImmutable|null          $created_at
  * @property-read Package|null                  $package
  */
@@ -45,6 +46,7 @@ protected function casts(): array
             'suggests' => 'array',
             'provides' => 'array',
             'artifacts' => 'array',
+            'reported' => 'immutable_datetime',
             'created_at' => 'immutable_datetime',
         ];
     }

app/Values/Packages/FairMetadata.php

@@ -101,6 +101,8 @@ public static function fromPackage(Package $package): array
             ->releases
             ->map(fn($release) => [
                 'version' => $release->version,
+                'reported' => $release->reported?->toIso8601String(),
+                'discovered' => $release->created_at?->toIso8601String(),
                 'artifacts' => $release->artifacts,
                 'provides' => $release->provides,
                 'requires' => $release->requires,

database/factories/PackageReleaseFactory.php

@@ -27,6 +27,7 @@ public function definition(): array
             'provides' => [
                 'some-feature' => $this->faker->semver(),
             ],
+            'reported' => $this->faker->dateTimeBetween('-1 year', 'now'),
             'artifacts' => [
                 'package' => [
                     [

database/migrations/2026_03_21_000000_add_reported_to_package_releases.php

@@ -0,0 +1,23 @@
+<?php
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('package_releases', function (Blueprint $table) {
+            $table->timestamp('reported')->nullable()->after('checksum');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('package_releases', function (Blueprint $table) {
+            $table->dropColumn('reported');
+        });
+    }
+};

tests/Feature/API/FAIR/PackageReleaseDatetimeFieldsTest.php

@@ -0,0 +1,74 @@
+<?php
+declare(strict_types=1);
+
+use App\Models\Package;
+
+beforeEach(function () {
+    Package::truncate();
+});
+
+it('includes reported and discovered datetime fields in release output', function () {
+    Package::factory()
+        ->withAuthors()
+        ->withReleases(1)
+        ->withMetas()
+        ->create([
+            'did' => 'fake:datetime-test',
+            'name' => 'Datetime Test Package',
+            'slug' => 'datetime-test',
+            'origin' => 'wp',
+            'type' => 'wp-plugin',
+            'license' => 'GPLv2',
+            'raw_metadata' => [],
+        ]);
+
+    $response = $this->getJson('/packages/fake:datetime-test')
+        ->assertStatus(200);
+
+    $releases = $response->json('releases');
+    expect($releases)->toBeArray()->not->toBeEmpty();
+
+    $release = $releases[0];
+    expect($release)
+        ->toHaveKeys(['reported', 'discovered'])
+        ->and($release['reported'])->toBeString()
+        ->and($release['discovered'])->toBeString();
+});
+
+it('returns null for reported when it is not set', function () {
+    $package = Package::factory()
+        ->withAuthors()
+        ->withMetas()
+        ->create([
+            'did' => 'fake:null-reported-test',
+            'name' => 'Null Reported Test',
+            'slug' => 'null-reported-test',
+            'origin' => 'wp',
+            'type' => 'wp-plugin',
+            'license' => 'GPLv2',
+            'raw_metadata' => [],
+        ]);
+
+    // Create a release without a reported value
+    $package->releases()->create([
+        'version' => '1.0.0',
+        'download_url' => 'https://example.com/test.zip',
+        'reported' => null,
+        'artifacts' => [
+            'package' => [['url' => 'https://example.com/test.zip', 'type' => 'zip']],
+        ],
+    ]);
+
+    $response = $this->getJson('/packages/fake:null-reported-test')
+        ->assertStatus(200);
+
+    $releases = $response->json('releases');
+    expect($releases)->toBeArray()->not->toBeEmpty();
+
+    $release = $releases[0];
+    expect($release)
+        ->toHaveKey('reported')
+        ->toHaveKey('discovered')
+        ->and($release['reported'])->toBeNull()
+        ->and($release['discovered'])->toBeString();
+});