GitHub #369: Prepare to ship 2.0 schema and code as a clean slate (#533)

Author: durable-workflow-ops

src/V2/Support/BundleIntegrityVerifier.php

@@ -181,7 +181,7 @@ private static function checkSchema(array $bundle, array &$findings): void
                 'bundle.schema_version_unsupported',
                 self::SEVERITY_ERROR,
                 sprintf(
-                    'Bundle schema_version %d is not supported by this verifier (expected %d).',
+                    'Bundle schema_version %d is not the v2 history-export structural marker (%d); the v2 bundle shape is frozen and a different value indicates a parallel primitive that this verifier does not recognize.',
                     $version,
                     HistoryExport::SCHEMA_VERSION,
                 ),

src/V2/Support/HistoryExport.php

@@ -23,10 +23,27 @@
 use Workflow\V2\Models\WorkflowTask;
 use Workflow\V2\Models\WorkflowUpdate;
 
+/**
+ * Builds the v2 workflow history-export bundle.
+ *
+ * The schema is defined once for the v2 release. The schema id
+ * `durable-workflow.v2.history-export` is the canonical version anchor,
+ * and there is no schema_version ladder within v2: the bundle has a
+ * single, frozen shape for the lifetime of v2. The accompanying
+ * `schema_version` field is a structural marker that must remain `1`
+ * for the lifetime of v2; a breaking shape change requires a parallel
+ * primitive (a new schema id alongside the existing one) under the
+ * `parallel_primitive_only` evolution rule, never a bump within v2.
+ */
 final class HistoryExport
 {
     public const SCHEMA = 'durable-workflow.v2.history-export';
 
+    /**
+     * Frozen structural marker for the v2 history-export bundle. Do not
+     * bump this within v2 — see the class docblock for why a breaking
+     * shape change must take the parallel-primitive route instead.
+     */
     public const SCHEMA_VERSION = 1;
 
     private const INTEGRITY_CANONICALIZATION = 'json-recursive-ksort-v1';

src/V2/Support/PlatformProtocolSpecs.php

@@ -38,7 +38,7 @@ final class PlatformProtocolSpecs
 {
     public const SCHEMA = 'durable-workflow.v2.platform-protocol-specs.catalog';
 
-    public const VERSION = 11;
+    public const VERSION = 12;
 
     public const AUTHORITY_URL = 'https://durable-workflow.github.io/docs/2.0/platform-protocol-specs';
 
@@ -420,7 +420,7 @@ private static function specs(): array
                 'companion_doc' => 'docs/api-stability.md frozen-event tables in `durable-workflow/workflow`',
             ],
             'history_export_bundle' => [
-                'description' => 'JSON Schema for the history-export bundle that the server emits and that replay tooling consumes: ordered history events, payload references, payload codec metadata, lineage edges, and bundle manifest.',
+                'description' => 'JSON Schema for the history-export bundle that the server emits and that replay tooling consumes: ordered history events, payload references, payload codec metadata, lineage edges, and bundle manifest. The schema is defined once for the v2 release; the schema id `durable-workflow.v2.history-export` is the canonical version anchor and the only allowed breaking change is a parallel primitive (a new schema id alongside the existing one).',
                 'format' => self::FORMAT_JSON_SCHEMA,
                 'spec_id' => 'durable-workflow.v2.history-export-bundle',
                 'surface_family' => 'history_event_wire_formats',
@@ -432,11 +432,11 @@ private static function specs(): array
                         'name' => 'history_export_bundle',
                         'owner_repo' => 'durable-workflow/workflow',
                         'schema_authority' => 'Workflow\\V2\\Support\\HistoryExport::SCHEMA',
-                        'version_authority' => 'Workflow\\V2\\Support\\HistoryExport::SCHEMA_VERSION',
+                        'version_authority' => 'durable-workflow.v2.history-export',
                     ],
                 ],
-                'evolution_rule' => self::EVOLUTION_ADDITIVE_MINOR_BREAKING_MAJOR,
-                'breaking_change_release' => 'major',
+                'evolution_rule' => self::EVOLUTION_PARALLEL_PRIMITIVE_ONLY,
+                'breaking_change_release' => self::EVOLUTION_PARALLEL_PRIMITIVE_ONLY,
                 'conformance_test' => 'durable-workflow/workflow: tests/Unit/V2/HistoryExportTest.php',
                 'status' => self::STATUS_PUBLISHED,
                 'spec_path' => 'static/platform-protocol-specs/history-export-bundle.schema.json',

tests/Unit/V2/HistoryExportTest.php

@@ -44,6 +44,20 @@
 
 final class HistoryExportTest extends TestCase
 {
+    public function testV2HistoryExportSchemaIsDefinedOnceForV2(): void
+    {
+        $this->assertSame(
+            'durable-workflow.v2.history-export',
+            HistoryExport::SCHEMA,
+            'the schema id is the canonical version anchor for the v2 history-export bundle',
+        );
+        $this->assertSame(
+            1,
+            HistoryExport::SCHEMA_VERSION,
+            'schema_version is a frozen structural marker for v2; a breaking shape change requires a parallel primitive (a new schema id), not a bump within v2',
+        );
+    }
+
     public function testItDoesNotBackfillCommandContractsDuringExport(): void
     {
         $instance = WorkflowInstance::query()->create([

tests/Unit/V2/PlatformProtocolSpecsTest.php

@@ -28,7 +28,7 @@ public function testManifestAdvertisesAuthorityIdentity(): void
         $manifest = PlatformProtocolSpecs::manifest();
 
         $this->assertSame('durable-workflow.v2.platform-protocol-specs.catalog', $manifest['schema']);
-        $this->assertSame(11, $manifest['version']);
+        $this->assertSame(12, $manifest['version']);
         $this->assertSame(
             'https://durable-workflow.github.io/docs/2.0/platform-protocol-specs',
             $manifest['authority_url'],
@@ -225,6 +225,27 @@ public function testHistoryEventPayloadsAreFrozenViaParallelPrimitiveRule(): voi
         );
     }
 
+    public function testHistoryExportBundleIsFrozenViaParallelPrimitiveRule(): void
+    {
+        $manifest = PlatformProtocolSpecs::manifest();
+
+        $entry = $manifest['specs']['history_export_bundle'];
+        $this->assertSame(
+            'parallel_primitive_only',
+            $entry['evolution_rule'],
+            'the v2 history-export bundle is defined once for v2; a breaking shape change must take the parallel-primitive route, not bump a schema_version ladder within v2',
+        );
+        $this->assertSame(
+            'parallel_primitive_only',
+            $entry['breaking_change_release'],
+        );
+        $this->assertSame(
+            'durable-workflow.v2.history-export',
+            $entry['object_families'][0]['version_authority'],
+            'the schema id is the canonical version anchor for the v2 history-export bundle; there is no separate schema_version ladder authority within v2',
+        );
+    }
+
     public function testReleaseCheckNamesEnforcementGates(): void
     {
         $manifest = PlatformProtocolSpecs::manifest();