durable-workflow.github.io: update v2 changes

Author: durable-workflow-ops

docs/configuration/options.md

@@ -231,7 +231,7 @@ Use the projection rebuild command when older data, manual maintenance, or a fai
 php artisan workflow:v2:rebuild-projections --missing --prune-stale
 ```
 
-The command rebuilds the run-summary projection used by Waterline list and dashboard views, the `workflow_run_waits` projection used by selected-run wait detail, the `workflow_run_timeline_entries` projection used by selected-run history detail, the `workflow_run_timer_entries` projection used by selected-run timer detail, and the `workflow_run_lineage_entries` projection used by selected-run parent/child and continue-as-new detail. Use `--run-id=...` or `--instance-id=...` to scope a repair, `--missing` to skip summaries that already exist, `--prune-stale` to remove summaries whose run row no longer exists, `--dry-run` to inspect the affected rows first, and `--json` for deployment checks. `--needs-rebuild` also treats legacy timer projection rows with `workflow_run_timer_entries.schema_version = 0` as stale, so the rebuild pass upgrades older pre-`row_status` timer snapshots onto the current stored schema before Waterline detail or history export reports them as aligned. If the app overrides `workflows.v2.run_model`, `workflows.v2.run_summary_model`, `workflows.v2.run_wait_model`, `workflows.v2.run_timeline_entry_model`, `workflows.v2.run_timer_entry_model`, or `workflows.v2.run_lineage_entry_model`, the command uses those same configured models so the repair target matches Waterline's `operator_metrics.projections.run_summaries` health signal and selected-run detail payloads. The same support boundary applies on the core runtime path and reads too: `WorkflowStub` reservation/load/start plus workflow-task execution, current-run resolution, selected-run detail, Waterline detail, and history export honor the configured `instance_model`, `run_model`, `task_model`, `history_event_model`, and projection-model classes instead of silently falling back to the package defaults.
+The command rebuilds the run-summary projection used by Waterline list and dashboard views, the `workflow_run_waits` projection used by selected-run wait detail, the `workflow_run_timeline_entries` projection used by selected-run history detail, the `workflow_run_timer_entries` projection used by selected-run timer detail, and the `workflow_run_lineage_entries` projection used by selected-run parent/child and continue-as-new detail. Use `--run-id=...` or `--instance-id=...` to scope a repair, `--missing` to skip summaries that already exist, `--prune-stale` to remove summaries whose run row no longer exists, `--dry-run` to inspect the affected rows first, and `--json` for deployment checks. `--needs-rebuild` also treats legacy timer projection rows with `workflow_run_timer_entries.schema_version = 0` as stale, so the rebuild pass upgrades older pre-`row_status` timer snapshots onto the current stored schema before Waterline detail or history export reports them as aligned. `--needs-rebuild` also detects schema-outdated run summaries — rows whose `projection_schema_version` is `NULL` or lower than the current build's projector schema version. This covers the mixed-fleet upgrade case where older workers projected summaries without newer derived fields such as `namespace`, `search_attributes`, or `liveness_state`. After deploying a new package version across all workers, run `workflow:v2:rebuild-projections --needs-rebuild` to bring all schema-outdated summaries to the current projector schema. Re-projection is idempotent: running it on an already-current row produces the same output. If the app overrides `workflows.v2.run_model`, `workflows.v2.run_summary_model`, `workflows.v2.run_wait_model`, `workflows.v2.run_timeline_entry_model`, `workflows.v2.run_timer_entry_model`, or `workflows.v2.run_lineage_entry_model`, the command uses those same configured models so the repair target matches Waterline's `operator_metrics.projections.run_summaries` health signal and selected-run detail payloads. The same support boundary applies on the core runtime path and reads too: `WorkflowStub` reservation/load/start plus workflow-task execution, current-run resolution, selected-run detail, Waterline detail, and history export honor the configured `instance_model`, `run_model`, `task_model`, `history_event_model`, and projection-model classes instead of silently falling back to the package defaults.
 
 ## Parallel Group Metadata Backfill
 

docs/monitoring.md

@@ -315,6 +315,15 @@ Each list response now also echoes the resolved filter contract under `visibilit
 - `applied`: the merged filters after Waterline resolves any saved view and overlays the current query string
 - `saved_view`: the resolved saved-view payload when the request used `?view=...`
 
+The definition also includes `projection_schema_version`, which tracks the current derived-field schema that the run-summary projector writes. Summaries projected by an older package version may have `NULL` for fields added in later schema versions; exact-match filters will not match those rows until they are re-projected. The `workflow:v2:rebuild-projections --needs-rebuild` command detects schema-outdated summaries (where `projection_schema_version` is `NULL` or lower than the current build) and re-projects them from durable runtime state.
+
+The saved-views index response also includes `mixed_fleet_policy`, which describes how visibility filters behave when workers run different package versions concurrently:
+
+- Filter normalization is idempotent regardless of the worker package version that wrote the summary projection
+- Saved views remain readable across filter version bumps; updating a deprecated saved view rewrites it onto the current version
+- Mixed-fleet operation is safe during a rollout window — older workers continue projecting with their schema version, and the rebuild command brings all rows to the current schema after rollout completes
+- The health check surfaces `schema_outdated` alongside `missing`, `orphaned`, and `stale` in the `run_summary_projection` check, with the current `projection_schema_version` reported for operator reference
+
 Waterline v2 saved views persist those same exact-match filters server-side:
 
 ```text