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/app/FormBuilder/Bindings/BindingActivityLogger.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\FormBuilder\Bindings;
 
 use App\Models\FormBuilder\FormSubmission;
+use App\Support\Json\JsonCanonicalizer;
 use Spatie\Activitylog\Models\Activity;
 
 /**
@@ -23,9 +24,12 @@ final class BindingActivityLogger
 {
     public function logPass(FormSubmission $submission, BindingPassResult $result): void
     {
+        // RFC-WS-6 session 2.7 — canonicalize properties before they land
+        // in activity_log.properties (MySQL JSON column round-trip would
+        // otherwise reorder keys and break diff/regression assertions).
         $passActivity = activity()
             ->performedOn($submission)
-            ->withProperties([
+            ->withProperties(JsonCanonicalizer::canonicalize([
                 'binding_count' => count($result->applications),
                 'succeeded' => $result->successCount(),
                 'failed' => $result->failureCount(),
@@ -33,7 +37,7 @@ final class BindingActivityLogger
                 'person_provisioned' => $result->provisionedSubjectType === 'person',
                 'subject_type' => $result->provisionedSubjectType,
                 'subject_id' => $result->provisionedSubjectId,
-            ])
+            ]))
             ->log('form_submission.bindings_pass_completed');
 
         $parentActivityId = $passActivity instanceof Activity ? (string) $passActivity->id : null;
@@ -56,7 +60,7 @@ final class BindingActivityLogger
 
             activity()
                 ->performedOn($submission)
-                ->withProperties($properties)
+                ->withProperties(JsonCanonicalizer::canonicalize($properties))
                 ->log('form_submission.binding_applied');
         }
     }

api/app/Jobs/FormBuilder/DeliverFormWebhookJob.php

@@ -6,6 +6,7 @@ namespace App\Jobs\FormBuilder;
 
 use App\Enums\FormBuilder\FormWebhookDeliveryStatus;
 use App\Models\FormBuilder\FormWebhookDelivery;
+use App\Support\Json\JsonCanonicalizer;
 use Illuminate\Bus\Queueable;
 use Illuminate\Contracts\Queue\ShouldQueue;
 use Illuminate\Foundation\Bus\Dispatchable;
@@ -61,8 +62,13 @@ final class DeliverFormWebhookJob implements ShouldQueue
             return;
         }
 
+        // RFC-WS-6 session 2.7 — canonical JSON for HMAC signing.
+        // payload_snapshot was read from a MySQL JSON column whose key
+        // order may not match what we wrote. Canonicalize so the
+        // signature is byte-stable across re-deliveries and matches what
+        // a verifying receiver computes from the same logical payload.
         $payload = (array) ($delivery->payload_snapshot ?? []);
-        $body = json_encode($payload, JSON_THROW_ON_ERROR);
+        $body = JsonCanonicalizer::encode($payload);
 
         $headers = ['Content-Type' => 'application/json'];
         if (! empty($webhook->secret)) {
@@ -173,7 +179,7 @@ final class DeliverFormWebhookJob implements ShouldQueue
         }
         $maskLong = -1 << (32 - (int) $mask);
 
-        return (($ipLong & $maskLong) === ($subnetLong & $maskLong));
+        return ($ipLong & $maskLong) === ($subnetLong & $maskLong);
     }
 
     private function isRetriable(int $status): bool

api/app/Models/FormBuilder/FormField.php

@@ -7,6 +7,7 @@ namespace App\Models\FormBuilder;
 use App\Enums\FormBuilder\FormFieldDisplayWidth;
 use App\Enums\FormBuilder\FormValueStorageHint;
 use App\Models\Scopes\OrganisationScope;
+use App\Support\Json\JsonCanonicalizer;
 use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -32,7 +33,7 @@ final class FormField extends Model
 
     protected static function booted(): void
     {
-        static::addGlobalScope(new OrganisationScope());
+        self::addGlobalScope(new OrganisationScope);
     }
 
     /** @return array{via: class-string, fk: string} */
@@ -156,9 +157,13 @@ final class FormField extends Model
      */
     public function logFieldChange(string $event, array $properties = []): void
     {
+        // RFC-WS-6 session 2.7: properties land in activity_log.properties
+        // (MySQL JSON column). Canonicalize so diff/regression assertions
+        // and downstream consumers see byte-stable structure regardless of
+        // MySQL key-order normalization on round-trip.
         activity()
             ->performedOn($this)
-            ->withProperties($properties)
+            ->withProperties(JsonCanonicalizer::canonicalize($properties))
             ->log($event);
     }
 }

api/app/Models/FormBuilder/FormSchema.php

@@ -11,6 +11,7 @@ use App\Models\CrowdType;
 use App\Models\Organisation;
 use App\Models\Scopes\OrganisationScope;
 use App\Models\User;
+use App\Support\Json\JsonCanonicalizer;
 use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -33,7 +34,7 @@ final class FormSchema extends Model
 
     protected static function booted(): void
     {
-        static::addGlobalScope(new OrganisationScope());
+        self::addGlobalScope(new OrganisationScope);
     }
 
     protected $fillable = [
@@ -152,9 +153,13 @@ final class FormSchema extends Model
      */
     public function logSchemaChange(string $event, array $properties = []): void
     {
+        // RFC-WS-6 session 2.7: properties land in activity_log.properties
+        // (MySQL JSON column). Canonicalize so diff/regression assertions
+        // and downstream consumers see byte-stable structure regardless of
+        // MySQL key-order normalization on round-trip.
         activity()
             ->performedOn($this)
-            ->withProperties($properties)
+            ->withProperties(JsonCanonicalizer::canonicalize($properties))
             ->log($event);
     }
 }

api/app/Services/FormBuilder/FormSubmissionService.php

@@ -19,9 +19,9 @@ use App\Models\FormBuilder\FormSubmission;
 use App\Models\FormBuilder\FormSubmissionDelegation;
 use App\Models\FormBuilder\FormValue;
 use App\Models\User;
+use App\Support\Json\JsonCanonicalizer;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Facades\DB;
-use Illuminate\Support\Str;
 
 /**
  * Submission lifecycle: draft → submitted → reviewed per ARCH §4.3, §15.
@@ -103,7 +103,7 @@ final class FormSubmissionService
     {
         $this->assertWritable($submission);
 
-        $result = DB::transaction(function () use ($submission, $actor): FormSubmission {
+        $result = DB::transaction(function () use ($submission): FormSubmission {
             $schema = $submission->schema;
 
             $submission->status = FormSubmissionStatus::SUBMITTED->value;
@@ -111,7 +111,12 @@ final class FormSubmissionService
             $submission->schema_version_at_submit = $schema->version;
 
             if ($schema->snapshot_mode !== FormSchemaSnapshotMode::NEVER) {
-                $submission->schema_snapshot = $this->buildSnapshot($schema);
+                // RFC-WS-6 session 2.7: schema_snapshot is audit-immutable;
+                // canonicalize before storage so MySQL JSON-column round-trip
+                // can never corrupt audit-replay diffs or webhook signing.
+                $submission->schema_snapshot = JsonCanonicalizer::canonicalize(
+                    $this->buildSnapshot($schema),
+                );
             }
 
             if ($submission->opened_at !== null) {
@@ -272,7 +277,6 @@ final class FormSubmissionService
      * any residual options key defensively (commit 2 backfill should
      * already have done so on existing rows).
      *
-     * @param  mixed  $translations
      * @return array<string, mixed>|null
      */
     private function stripOptionsFromTranslations(mixed $translations): ?array

api/app/Services/FormBuilder/FormWebhookDispatcher.php

@@ -9,6 +9,7 @@ use App\Jobs\FormBuilder\DeliverFormWebhookJob;
 use App\Models\FormBuilder\FormSchemaWebhook;
 use App\Models\FormBuilder\FormSubmission;
 use App\Models\FormBuilder\FormWebhookDelivery;
+use App\Support\Json\JsonCanonicalizer;
 
 /**
  * Finds active webhooks for a submission's schema + trigger and queues a
@@ -36,7 +37,12 @@ final class FormWebhookDispatcher
                 'trigger_event' => $triggerEvent,
                 'status' => FormWebhookDeliveryStatus::PENDING->value,
                 'attempts' => 0,
-                'payload_snapshot' => $this->buildPayload($submission, $triggerEvent),
+                // RFC-WS-6 session 2.7 — canonicalize before storage; the
+                // delivery job HMAC-signs the same canonical bytes after
+                // re-encode, so signature is reproducible.
+                'payload_snapshot' => JsonCanonicalizer::canonicalize(
+                    $this->buildPayload($submission, $triggerEvent),
+                ),
             ]);
 
             DeliverFormWebhookJob::dispatch($delivery->id)->onConnection('webhooks')->onQueue('webhooks');

api/app/Support/Json/JsonCanonicalizer.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Support\Json;
+
+/**
+ * Canonical JSON encoding for byte-stable storage.
+ *
+ * MySQL 8.0 JSON columns may reorder associative-array keys on
+ * round-trip. For values that need byte-stability (schema snapshots,
+ * webhook payloads signed via HMAC, audit-replay diffs), canonicalize
+ * the structure before encode so re-emits produce identical bytes.
+ *
+ * Strategy:
+ * - Associative arrays: recursively ksort
+ * - Numeric-indexed lists (`array_is_list()`): preserve order
+ *   (semantically ordered)
+ * - Scalars and non-arrays: passthrough
+ *
+ * Numeric vs associative detection follows array_is_list() — PHP 8.1+
+ * convention. Mixed-key arrays are treated as associative (rare and
+ * indicative of a data issue worth surfacing rather than papering over).
+ *
+ * RFC-WS-6 session 2.7 — see also CLAUDE.md "Database" section
+ * (byte-stability rule for JSON columns).
+ */
+final class JsonCanonicalizer
+{
+    /**
+     * Canonicalize the structure recursively (sort associative keys).
+     *
+     * @template T
+     *
+     * @param  T  $value
+     * @return T
+     */
+    public static function canonicalize(mixed $value): mixed
+    {
+        if (! is_array($value)) {
+            return $value;
+        }
+
+        if ($value === []) {
+            return $value;
+        }
+
+        if (array_is_list($value)) {
+            return array_map(self::canonicalize(...), $value);
+        }
+
+        ksort($value);
+        foreach ($value as $key => $child) {
+            $value[$key] = self::canonicalize($child);
+        }
+
+        return $value;
+    }
+
+    /**
+     * Encode a value as canonical JSON.
+     *
+     * Use for values stored in MySQL JSON columns where byte-stability
+     * matters across reads/writes.
+     *
+     * @throws \JsonException
+     */
+    public static function encode(mixed $value): string
+    {
+        return json_encode(
+            self::canonicalize($value),
+            JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR,
+        );
+    }
+}