fix(form-builder): canonicalize JSON for byte-stable storage (WS-6)

MySQL 8.0 JSON columns may reorder associative-array keys on
round-trip. For audit-immutable values (schema snapshots, webhook
payloads, activity log diffs), this is corrupting: re-emits produce
different byte sequences for the same logical content.

Introduced JsonCanonicalizer (recursive ksort on associative arrays;
numeric-indexed lists preserve order) and applied at every writer
site that produces byte-stable JSON:

- FormSubmissionService: canonicalize the schema_snapshot array
  before storage (audit-immutable per ARCH §4.3, RFC-WS-6 v1.1).
- FormField::logFieldChange / FormSchema::logSchemaChange: canonicalize
  activity-log properties before withProperties() so old/new diffs
  read back byte-stable.
- BindingActivityLogger: canonicalize both the pass-level and
  per-binding activity properties.
- FormWebhookDispatcher: canonicalize payload_snapshot before
  storage (delivery-time HMAC re-encodes the same canonical bytes).
- DeliverFormWebhookJob: switched json_encode to
  JsonCanonicalizer::encode for the HMAC-signed body, so the
  signature is byte-stable across re-deliveries and reproducible by
  receivers from the same logical payload.

Sites NOT canonicalized (deliberate):
- form_schemas.settings — opaque UI config; key order has no
  semantic meaning, no byte-stability requirement.
- form_schemas.translations / form_fields.translations — read by
  display layer; key order doesn't matter.
- form_templates.schema_snapshot — user-supplied input via store/
  update; user is the source of truth, not audit-immutable in the
  same way as form_submissions.schema_snapshot.

Reverted the 7 assertEquals workarounds from session 2.6:
- ConditionalLogicActivityLogPayloadTest
- ConditionalLogicBackfillTest::test_rollback_reconstructs_canonical_json
- FormFieldBindingMigrationTest::test_rollback_reconstructs_json_and_drops_table
- FormFieldOptionServiceAndScopeTest::test_replace_options_emits_activity_log_on_field_only
- FormFieldOptionsActivityLogTest::test_field_updated_payload_contains_options_diff_when_options_change
- FormFieldOptionsBackfillTest::test_forward_migration_backfills_rows_strips_translations_and_rewrites_snapshot
- FormFieldOptionsSnapshotAndStrictRequestTest::test_submission_snapshot_embeds_rich_shape_options

Each now uses assertSame on JsonCanonicalizer::encode of both sides —
byte-stable comparison meaningful regardless of MySQL JSON storage
behavior.

New regression test SchemaSnapshotByteStableAcrossReemitsTest
exercises the contract end-to-end: complex schema with bindings,
validation rules, options, conditional logic, submitted; reads
schema_snapshot via three roads (Eloquent cast, fresh model, raw
bytes) and asserts the canonical encode is identical.

ARCH-FORM-BUILDER.md §4.6.1 gets a "Byte-stability" sub-section
explaining what's canonicalized and why.

Test count: 1388 → 1400 (+11 JsonCanonicalizer unit, +1 snapshot
regression). Larastan clean. Rector dry-run unchanged at 355.

Refs: WS-6 session 2.6 deviation #4 cleanup, RFC-WS-6 v1.1

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

api/tests/Feature/FormBuilder/Options/FormFieldOptionServiceAndScopeTest.php

@@ -12,6 +12,7 @@ use App\Models\FormBuilder\FormSchema;
 use App\Models\Organisation;
 use App\Models\Scopes\FormFieldOptionScope;
 use App\Services\FormBuilder\FormFieldOptionService;
+use App\Support\Json\JsonCanonicalizer;
 use Illuminate\Database\QueryException;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Routing\Route;
@@ -191,11 +192,12 @@ final class FormFieldOptionServiceAndScopeTest extends TestCase
             ->where('description', 'field.options_replaced')
             ->first();
         $this->assertNotNull($fieldEvent);
-        // assertEquals: MySQL JSON columns may reorder associative-array
-        // keys on round-trip; semantic content is what matters here.
-        $this->assertEquals(
-            [['value' => 'a', 'label' => 'A', 'sort_order' => 0]],
-            $fieldEvent->properties->get('options'),
+        // RFC-WS-6 session 2.7: activity log properties are canonicalized
+        // at write; assertSame on canonical encodings of both sides is
+        // byte-stable across MySQL JSON-column round-trip.
+        $this->assertSame(
+            JsonCanonicalizer::encode([['value' => 'a', 'label' => 'A', 'sort_order' => 0]]),
+            JsonCanonicalizer::encode($fieldEvent->properties->get('options')),
         );
 
         $this->assertNull(Activity::query()

api/tests/Feature/FormBuilder/Options/FormFieldOptionsActivityLogTest.php

@@ -11,6 +11,7 @@ use App\Models\FormBuilder\FormSchema;
 use App\Models\Organisation;
 use App\Services\FormBuilder\FormFieldOptionService;
 use App\Services\FormBuilder\FormFieldService;
+use App\Support\Json\JsonCanonicalizer;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Spatie\Activitylog\Models\Activity;
 use Tests\TestCase;
@@ -61,22 +62,23 @@ final class FormFieldOptionsActivityLogTest extends TestCase
         $payload = $event->properties->toArray();
         $this->assertArrayHasKey('options', $payload['old']);
         $this->assertArrayHasKey('options', $payload['new']);
-        // assertEquals: MySQL JSON columns may reorder associative-array
-        // keys on round-trip; structural equality is the contract.
-        $this->assertEquals(
-            [
+        // RFC-WS-6 session 2.7: activity log properties are canonicalized
+        // at write; assertSame on canonical encodings of both sides is
+        // byte-stable across MySQL JSON-column round-trip.
+        $this->assertSame(
+            JsonCanonicalizer::encode([
                 ['value' => 'a', 'label' => 'a', 'sort_order' => 0],
                 ['value' => 'b', 'label' => 'b', 'sort_order' => 1],
-            ],
-            $payload['old']['options'],
+            ]),
+            JsonCanonicalizer::encode($payload['old']['options']),
         );
-        $this->assertEquals(
-            [
+        $this->assertSame(
+            JsonCanonicalizer::encode([
                 ['value' => 'a', 'label' => 'A', 'sort_order' => 0],
                 ['value' => 'b', 'label' => 'b', 'sort_order' => 1],
                 ['value' => 'c', 'label' => 'c', 'sort_order' => 2],
-            ],
-            $payload['new']['options'],
+            ]),
+            JsonCanonicalizer::encode($payload['new']['options']),
         );
     }
 

api/tests/Feature/FormBuilder/Options/FormFieldOptionsBackfillTest.php

@@ -6,6 +6,7 @@ namespace Tests\Feature\FormBuilder\Options;
 
 use App\Models\FormBuilder\FormSchema;
 use App\Models\Organisation;
+use App\Support\Json\JsonCanonicalizer;
 use Illuminate\Foundation\Testing\RefreshDatabaseState;
 use Illuminate\Support\Facades\Artisan;
 use Illuminate\Support\Facades\DB;
@@ -99,13 +100,18 @@ final class FormFieldOptionsBackfillTest extends TestCase
         $submission = DB::table('form_submissions')->where('id', $submissionId)->first();
         $snapshot = json_decode((string) $submission->schema_snapshot, true);
         $field = $snapshot['fields'][0];
-        // assertEquals: MySQL JSON columns may reorder associative-array
-        // keys on round-trip; structural equality is the contract here.
-        $this->assertEquals([
-            ['value' => 'XS', 'label' => 'XS', 'sort_order' => 0, 'translations' => ['de' => 'Größe XS']],
-            ['value' => 'S', 'label' => 'S', 'sort_order' => 1, 'translations' => ['de' => 'Klein']],
-            ['value' => 'M', 'label' => 'M', 'sort_order' => 2, 'translations' => ['de' => 'Mittel']],
-        ], $field['options']);
+        // RFC-WS-6 session 2.7: this snapshot was rewritten by the
+        // migration's forward() (raw DB writer, not via the canonicalizing
+        // service). Compare on canonical form so the assertion is
+        // engine-agnostic.
+        $this->assertSame(
+            JsonCanonicalizer::encode([
+                ['value' => 'XS', 'label' => 'XS', 'sort_order' => 0, 'translations' => ['de' => 'Größe XS']],
+                ['value' => 'S', 'label' => 'S', 'sort_order' => 1, 'translations' => ['de' => 'Klein']],
+                ['value' => 'M', 'label' => 'M', 'sort_order' => 2, 'translations' => ['de' => 'Mittel']],
+            ]),
+            JsonCanonicalizer::encode($field['options']),
+        );
         // Field-level translations bag has the {locale}.options key
         // stripped.
         if (is_array($field['translations'] ?? null)) {
@@ -117,14 +123,14 @@ final class FormFieldOptionsBackfillTest extends TestCase
         // Template snapshot rewritten the same way.
         $template = DB::table('form_templates')->where('id', $templateId)->first();
         $tplSnap = json_decode((string) $template->schema_snapshot, true);
-        // assertEquals: MySQL JSON columns may reorder associative-array
-        // keys on round-trip; structural equality is the contract here.
-        $this->assertEquals(
-            [
+        // RFC-WS-6 session 2.7: snapshot rewritten by migration; compare
+        // on canonical form to be engine-agnostic.
+        $this->assertSame(
+            JsonCanonicalizer::encode([
                 ['value' => 'A', 'label' => 'A', 'sort_order' => 0],
                 ['value' => 'B', 'label' => 'B', 'sort_order' => 1],
-            ],
-            $tplSnap['fields'][0]['options'],
+            ]),
+            JsonCanonicalizer::encode($tplSnap['fields'][0]['options']),
         );
     }
 

api/tests/Feature/FormBuilder/Options/FormFieldOptionsSnapshotAndStrictRequestTest.php

@@ -9,6 +9,7 @@ use App\Models\FormBuilder\FormField;
 use App\Models\FormBuilder\FormSchema;
 use App\Models\Organisation;
 use App\Services\FormBuilder\FormSubmissionService;
+use App\Support\Json\JsonCanonicalizer;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Tests\TestCase;
 
@@ -46,15 +47,16 @@ final class FormFieldOptionsSnapshotAndStrictRequestTest extends TestCase
         $snapshot = $draft->fresh()->schema_snapshot;
         $this->assertIsArray($snapshot);
         $field = collect($snapshot['fields'])->firstWhere('slug', 'shirtmaat');
-        // assertEquals: MySQL JSON columns may reorder associative-array
-        // keys on round-trip; structural equality is the contract.
-        $this->assertEquals(
-            [
+        // RFC-WS-6 session 2.7: schema_snapshot is canonicalized at write,
+        // so byte equality holds when both sides go through
+        // JsonCanonicalizer::encode.
+        $this->assertSame(
+            JsonCanonicalizer::encode([
                 ['value' => 'XS', 'label' => 'XS', 'sort_order' => 0],
                 ['value' => 'S', 'label' => 'S', 'sort_order' => 1],
                 ['value' => 'M', 'label' => 'M', 'sort_order' => 2],
-            ],
-            $field['options'],
+            ]),
+            JsonCanonicalizer::encode($field['options']),
         );
     }