Collapse visibility filters to the clean-slate v2 contract

Collapse visibility filter contract to current v2 version

Author: durable-workflow-ops

src/V2/Support/VisibilityFilters.php

@@ -13,8 +13,6 @@ final class VisibilityFilters
 {
     public const VERSION = 6;
 
-    public const MINIMUM_SUPPORTED_VERSION = 1;
-
     private const FIELD_LABELS = [
         'instance_id' => 'Instance ID',
         'run_id' => 'Run ID',
@@ -83,87 +81,21 @@ final class VisibilityFilters
 
     private const LABEL_KEY_PATTERN = '/^[A-Za-z0-9_.:-]{1,64}$/';
 
-    private const DEPRECATED_VERSIONS = [1, 2];
-
     private const RESERVED_VIEW_ID_PREFIX = 'system:';
 
     /**
      * @return list<int>
      */
     public static function supportedVersions(): array
     {
-        return [1, 2, 3, 4, 5, self::VERSION];
-    }
-
-    public static function minimumSupportedVersion(): int
-    {
-        return self::MINIMUM_SUPPORTED_VERSION;
-    }
-
-    public static function isDeprecated(int $version): bool
-    {
-        return in_array($version, self::DEPRECATED_VERSIONS, true);
+        return [self::VERSION];
     }
 
     public static function isReservedViewId(string $id): bool
     {
         return str_starts_with($id, self::RESERVED_VIEW_ID_PREFIX);
     }
 
-    /**
-     * @return array{
-     *     current_version: int,
-     *     minimum_supported_version: int,
-     *     supported_versions: list<int>,
-     *     deprecated_versions: list<int>,
-     *     reserved_view_id_prefix: string,
-     *     upgrade_policy: string
-     * }
-     */
-    public static function versionEvolutionPolicy(): array
-    {
-        return [
-            'current_version' => self::VERSION,
-            'minimum_supported_version' => self::MINIMUM_SUPPORTED_VERSION,
-            'supported_versions' => self::supportedVersions(),
-            'deprecated_versions' => self::DEPRECATED_VERSIONS,
-            'reserved_view_id_prefix' => self::RESERVED_VIEW_ID_PREFIX,
-            'upgrade_policy' => 'Saved views written against any supported version remain readable. '
-                . 'Updating a saved view rewrites it onto the current version. '
-                . 'Deprecated versions are still loadable but should be migrated to the current version. '
-                . 'Versions below the minimum supported version are rejected.',
-        ];
-    }
-
-    /**
-     * Machine-readable policy describing how visibility filters behave when
-     * workers run different package versions concurrently and when projection
-     * rebuilds are authoritative for derived filter fields.
-     *
-     * @return array<string, mixed>
-     */
-    public static function mixedFleetPolicy(): array
-    {
-        return [
-            'projection_schema_version' => RunSummaryProjector::SCHEMA_VERSION,
-            'filter_version' => self::VERSION,
-            'invariants' => [
-                'Filter normalization is idempotent regardless of the worker package version that wrote the summary projection.',
-                'Summaries projected by older workers may have NULL for fields added in later schema versions; exact-match filters will not match NULL, so those rows are excluded from filtered views until re-projected.',
-                'The rebuild-projections command re-projects from durable runtime state, filling in any derived fields missing from older schema versions.',
-                'Saved views remain readable across filter version bumps; updating a deprecated saved view rewrites it onto the current version.',
-                'Boolean and base string filter fields use exact-match semantics; explicit *_contains string filters use escaped SQL LIKE substring matching on the run-summary projection.',
-            ],
-            'projection_backfill_authority' => [
-                'trigger' => 'Summaries with a NULL or lower projection_schema_version than the current build need re-projection.',
-                'mechanism' => 'workflow:v2:rebuild-projections --needs-rebuild detects schema-outdated rows and re-projects them from durable state.',
-                'scope' => 'Re-projection populates all current derived fields including namespace, search_attributes, visibility_labels, liveness_state, wait_kind, repair_blocked_reason, task_problem, and history budget.',
-                'safety' => 'Re-projection is idempotent. Running it on an already-current row produces the same output.',
-            ],
-            'upgrade_path' => 'Deploy the new package version to all workers, then run workflow:v2:rebuild-projections --needs-rebuild to backfill schema-outdated summaries. Mixed-fleet operation is safe during the rollout window — older workers continue projecting with their schema version, and the rebuild command brings all rows to the current schema after rollout completes.',
-        ];
-    }
-
     /**
      * @return array<int, string>
      */
@@ -202,9 +134,7 @@ public static function definition(): array
 
         return [
             'version' => self::VERSION,
-            'minimum_supported_version' => self::MINIMUM_SUPPORTED_VERSION,
             'supported_versions' => self::supportedVersions(),
-            'deprecated_versions' => self::DEPRECATED_VERSIONS,
             'reserved_view_id_prefix' => self::RESERVED_VIEW_ID_PREFIX,
             'fields' => $fields,
             'labels' => [
@@ -243,7 +173,6 @@ public static function definition(): array
      * @return array{
      *     version: int|null,
      *     current_version: int,
-     *     minimum_supported_version: int,
      *     supported_versions: list<int>,
      *     supported: bool,
      *     deprecated: bool,
@@ -256,29 +185,21 @@ public static function versionMetadata(mixed $version): array
         $normalizedVersion = self::normalizeVersion($version);
         $supportedVersions = self::supportedVersions();
         $supported = $normalizedVersion !== null && in_array($normalizedVersion, $supportedVersions, true);
-        $deprecated = $supported && self::isDeprecated($normalizedVersion);
 
         $status = match (true) {
             ! $supported => 'unsupported',
-            $deprecated => 'deprecated',
             default => 'supported',
         };
 
         return [
             'version' => $normalizedVersion,
             'current_version' => self::VERSION,
-            'minimum_supported_version' => self::MINIMUM_SUPPORTED_VERSION,
             'supported_versions' => $supportedVersions,
             'supported' => $supported,
-            'deprecated' => $deprecated,
+            'deprecated' => false,
             'status' => $status,
             'message' => match (true) {
                 ! $supported => self::unsupportedVersionMessage($normalizedVersion, $supportedVersions),
-                $deprecated => sprintf(
-                    'This saved view uses deprecated visibility filter version %d. Consider updating it to the current version %d.',
-                    $normalizedVersion,
-                    self::VERSION,
-                ),
                 default => null,
             },
         ];

tests/Feature/V2/V2SearchAttributeTest.php

@@ -175,8 +175,6 @@ public function testVisibilityFiltersDefinitionIncludesSearchAttributes(): void
     public function testVisibilityFilterVersionIsUpdated(): void
     {
         $this->assertSame(6, VisibilityFilters::VERSION);
-        $this->assertContains(6, VisibilityFilters::supportedVersions());
-        $this->assertContains(5, VisibilityFilters::supportedVersions());
-        $this->assertContains(3, VisibilityFilters::supportedVersions());
+        $this->assertSame([6], VisibilityFilters::supportedVersions());
     }
 }

tests/Unit/V2/VisibilityFiltersTest.php

@@ -322,7 +322,7 @@ public function testDefinitionDescribesExactVisibilityContract(): void
         $definition = VisibilityFilters::definition();
 
         $this->assertSame(VisibilityFilters::VERSION, $definition['version']);
-        $this->assertSame([1, 2, 3, 4, 5, VisibilityFilters::VERSION], $definition['supported_versions']);
+        $this->assertSame([VisibilityFilters::VERSION], $definition['supported_versions']);
         $this->assertSame('Instance ID', $definition['fields']['instance_id']['label']);
         $this->assertSame('string', $definition['fields']['instance_id']['type']);
         $this->assertSame('text', $definition['fields']['instance_id']['input']);
@@ -493,68 +493,37 @@ public function testVersionMetadataMarksUnsupportedSavedViewContractsExplicitly(
 
         $this->assertSame(VisibilityFilters::VERSION, $supported['version']);
         $this->assertSame(VisibilityFilters::VERSION, $supported['current_version']);
-        $this->assertSame(VisibilityFilters::MINIMUM_SUPPORTED_VERSION, $supported['minimum_supported_version']);
-        $this->assertSame([1, 2, 3, 4, 5, VisibilityFilters::VERSION], $supported['supported_versions']);
+        $this->assertSame([VisibilityFilters::VERSION], $supported['supported_versions']);
         $this->assertTrue($supported['supported']);
         $this->assertFalse($supported['deprecated']);
         $this->assertSame('supported', $supported['status']);
         $this->assertNull($supported['message']);
 
         $this->assertSame(99, $unsupported['version']);
         $this->assertSame(VisibilityFilters::VERSION, $unsupported['current_version']);
-        $this->assertSame(VisibilityFilters::MINIMUM_SUPPORTED_VERSION, $unsupported['minimum_supported_version']);
-        $this->assertSame([1, 2, 3, 4, 5, VisibilityFilters::VERSION], $unsupported['supported_versions']);
+        $this->assertSame([VisibilityFilters::VERSION], $unsupported['supported_versions']);
         $this->assertFalse($unsupported['supported']);
         $this->assertFalse($unsupported['deprecated']);
         $this->assertSame('unsupported', $unsupported['status']);
         $this->assertSame(
-            'This saved view uses visibility filter version 99, but this Waterline build supports version 1, 2, 3, 4, 5, 6.',
+            'This saved view uses visibility filter version 99, but this Waterline build supports version 6.',
             $unsupported['message'],
         );
     }
 
-    public function testVersionMetadataMarksDeprecatedVersionsExplicitly(): void
+    public function testVersionMetadataRejectsPreStableV2AlphaVersions(): void
     {
-        $deprecated = VisibilityFilters::versionMetadata(1);
+        $alphaVersion = VisibilityFilters::versionMetadata(1);
 
-        $this->assertSame(1, $deprecated['version']);
-        $this->assertSame(VisibilityFilters::VERSION, $deprecated['current_version']);
-        $this->assertTrue($deprecated['supported']);
-        $this->assertTrue($deprecated['deprecated']);
-        $this->assertSame('deprecated', $deprecated['status']);
+        $this->assertSame(1, $alphaVersion['version']);
+        $this->assertSame(VisibilityFilters::VERSION, $alphaVersion['current_version']);
+        $this->assertFalse($alphaVersion['supported']);
+        $this->assertFalse($alphaVersion['deprecated']);
+        $this->assertSame('unsupported', $alphaVersion['status']);
         $this->assertSame(
-            'This saved view uses deprecated visibility filter version 1. Consider updating it to the current version 6.',
-            $deprecated['message'],
+            'This saved view uses visibility filter version 1, but this Waterline build supports version 6.',
+            $alphaVersion['message'],
         );
-
-        $deprecated2 = VisibilityFilters::versionMetadata(2);
-        $this->assertTrue($deprecated2['supported']);
-        $this->assertTrue($deprecated2['deprecated']);
-        $this->assertSame('deprecated', $deprecated2['status']);
-
-        $notDeprecated = VisibilityFilters::versionMetadata(3);
-        $this->assertTrue($notDeprecated['supported']);
-        $this->assertFalse($notDeprecated['deprecated']);
-        $this->assertSame('supported', $notDeprecated['status']);
-        $this->assertNull($notDeprecated['message']);
-    }
-
-    public function testVersionEvolutionPolicyExposesStableContract(): void
-    {
-        $policy = VisibilityFilters::versionEvolutionPolicy();
-
-        $this->assertSame(VisibilityFilters::VERSION, $policy['current_version']);
-        $this->assertSame(VisibilityFilters::MINIMUM_SUPPORTED_VERSION, $policy['minimum_supported_version']);
-        $this->assertSame([1, 2, 3, 4, 5, VisibilityFilters::VERSION], $policy['supported_versions']);
-        $this->assertSame([1, 2], $policy['deprecated_versions']);
-        $this->assertSame('system:', $policy['reserved_view_id_prefix']);
-        $this->assertIsString($policy['upgrade_policy']);
-
-        foreach ($policy['deprecated_versions'] as $version) {
-            $this->assertTrue(VisibilityFilters::isDeprecated($version));
-            $this->assertContains($version, $policy['supported_versions']);
-            $this->assertGreaterThanOrEqual($policy['minimum_supported_version'], $version);
-        }
     }
 
     public function testIsReservedViewIdGuardsSystemPrefix(): void
@@ -567,12 +536,13 @@ public function testIsReservedViewIdGuardsSystemPrefix(): void
         $this->assertFalse(VisibilityFilters::isReservedViewId(''));
     }
 
-    public function testDefinitionIncludesVersionEvolutionFields(): void
+    public function testDefinitionIncludesCleanSlateVersionFields(): void
     {
         $definition = VisibilityFilters::definition();
 
-        $this->assertSame(VisibilityFilters::MINIMUM_SUPPORTED_VERSION, $definition['minimum_supported_version']);
-        $this->assertSame([1, 2], $definition['deprecated_versions']);
+        $this->assertSame([VisibilityFilters::VERSION], $definition['supported_versions']);
+        $this->assertArrayNotHasKey('minimum_supported_version', $definition);
+        $this->assertArrayNotHasKey('deprecated_versions', $definition);
         $this->assertSame('system:', $definition['reserved_view_id_prefix']);
     }
 
@@ -675,31 +645,6 @@ public function testDefinitionIncludesProjectionSchemaVersion(): void
         $this->assertGreaterThanOrEqual(1, $definition['projection_schema_version']);
     }
 
-    public function testMixedFleetPolicyExposesStableContract(): void
-    {
-        $policy = VisibilityFilters::mixedFleetPolicy();
-
-        $this->assertSame(RunSummaryProjector::SCHEMA_VERSION, $policy['projection_schema_version']);
-        $this->assertSame(VisibilityFilters::VERSION, $policy['filter_version']);
-        $this->assertIsArray($policy['invariants']);
-        $this->assertNotEmpty($policy['invariants']);
-
-        foreach ($policy['invariants'] as $invariant) {
-            $this->assertIsString($invariant);
-            $this->assertNotEmpty($invariant);
-        }
-
-        $this->assertArrayHasKey('projection_backfill_authority', $policy);
-        $backfill = $policy['projection_backfill_authority'];
-        $this->assertArrayHasKey('trigger', $backfill);
-        $this->assertArrayHasKey('mechanism', $backfill);
-        $this->assertArrayHasKey('scope', $backfill);
-        $this->assertArrayHasKey('safety', $backfill);
-
-        $this->assertIsString($policy['upgrade_path']);
-        $this->assertNotEmpty($policy['upgrade_path']);
-    }
-
     public function testApplyFiltersExcludeRowsWithNullVisibilityFieldsFromFilteredViews(): void
     {
         WorkflowRunSummary::create([