durable-workflow.github.io: update v2 changes

Author: durable-workflow-ops

docs/monitoring.md

@@ -294,19 +294,22 @@ For list screens, the current Waterline build now exposes:
 
 The last three are all terminal views. `cancelled` and `terminated` still carry `status_bucket = failed` in each row for compatibility, but the list routing no longer forces operator-driven closures to share the exact same screen as actual failures.
 
-Those list routes also accept exact-match filters for `instance_id`, `run_id`, `workflow_type`, `business_key`, `compatibility`, `declared_entry_mode`, `declared_contract_source`, `declared_contract_backfill_needed`, `declared_contract_backfill_available`, `connection`, `queue`, `status`, `status_bucket`, `closed_reason`, `wait_kind`, `liveness_state`, `repair_blocked_reason`, `repair_attention`, `task_problem`, `is_current_run`, `continue_as_new_recommended`, `archived`, and `is_terminal`. Visibility labels can be filtered with either `label[key]=value` or `labels[key]=value`, for example:
+Those list routes also accept exact-match filters for `instance_id`, `run_id`, `namespace`, `workflow_type`, `business_key`, `compatibility`, `declared_entry_mode`, `declared_contract_source`, `declared_contract_backfill_needed`, `declared_contract_backfill_available`, `connection`, `queue`, `status`, `status_bucket`, `closed_reason`, `wait_kind`, `liveness_state`, `repair_blocked_reason`, `repair_attention`, `task_problem`, `is_current_run`, `continue_as_new_recommended`, `archived`, and `is_terminal`. Visibility labels can be filtered with either `label[key]=value` or `labels[key]=value`, and search attributes with `search_attribute[key]=value` or `search_attributes[key]=value`, for example:
 
 ```text
-GET /waterline/api/flows/running?declared_entry_mode=compatibility&declared_contract_source=live_definition&declared_contract_backfill_needed=true&repair_blocked_reason=unsupported_history&workflow_type=billing.invoice-sync&instance_id=order-123&label[tenant]=acme
+GET /waterline/api/flows/running?declared_entry_mode=compatibility&declared_contract_source=live_definition&declared_contract_backfill_needed=true&repair_blocked_reason=unsupported_history&workflow_type=billing.invoice-sync&instance_id=order-123&label[tenant]=acme&search_attribute[priority]=high
 ```
 
-Selected-run detail and history export also return `memo`, but `memo` is intentionally not part of the list-filter contract, run-summary projection, or saved-view matching. Use `business_key` and `visibility_labels` for searchable fleet metadata, and use `memo` for returned-only per-run context.
+Selected-run detail and history export also return `memo`, but `memo` is intentionally not part of the list-filter contract, run-summary projection, or saved-view matching. Use `business_key`, `visibility_labels`, and `search_attributes` for searchable fleet metadata, and use `memo` for returned-only per-run context.
 
-That searchable-versus-returned-only boundary is now machine-readable too: `visibility_filters.definition.indexed_metadata` describes the exact-match searchable metadata that Waterline can persist in saved views today, while `visibility_filters.definition.detail_metadata` calls out returned-only metadata such as `memo` that stays visible on selected-run detail and history export but never participates in list filtering or saved-view matching.
+That searchable-versus-returned-only boundary is now machine-readable too: `visibility_filters.definition.indexed_metadata` describes the exact-match searchable metadata that Waterline can persist in saved views today (including `business_key`, `labels`, and `search_attributes`), while `visibility_filters.definition.detail_metadata` calls out returned-only metadata such as `memo` that stays visible on selected-run detail and history export but never participates in list filtering or saved-view matching.
 
 Each list response now also echoes the resolved filter contract under `visibility_filters`:
 
-- `version`: the current workflow visibility filter contract version. Current builds emit `3` and still support saved views written against versions `1`, `2`, and `3`
+- `version`: the current workflow visibility filter contract version. Current builds emit `5` and still support saved views written against versions `1` through `5`. Versions `1` and `2` are deprecated but remain loadable; updating a deprecated saved view rewrites it onto the current version
+- `minimum_supported_version`: the oldest filter version the current build will accept
+- `deprecated_versions`: filter versions that are still loadable but should be migrated to the current version
+- `reserved_view_id_prefix`: the ID prefix reserved for system views (currently `system:`); custom views must not use this prefix
 - `bucket`: the list bucket that was queried
 - `definition`: the exact-match field and label contract the current build understands, including field labels, editor input types, bounded-field option catalogs, query-parameter names, ordering, field help text, label-editor metadata such as the accepted key pattern and placeholder, plus `indexed_metadata` and `detail_metadata` entries that distinguish searchable saved-view-compatible operator metadata from returned-only detail metadata
 - `applied`: the merged filters after Waterline resolves any saved view and overlays the current query string
@@ -322,7 +325,7 @@ DELETE /waterline/api/saved-views/{viewId}
 GET  /waterline/api/flows/running?view=01J20000000000000000000000
 ```
 
-A saved view records `name`, `bucket`, `scope`, `shared`, `filter_version`, and normalized `filters` using the workflow v2 visibility filter contract. `GET /waterline/api/saved-views?bucket=...` now also returns `filter_definition` plus `supported_filter_versions` so operator clients can render the same current field contract they save against, even if no custom views exist yet. Each saved-view payload echoes `filter_version_supported`, `filter_version_status`, `filter_version_message`, `current_filter_version`, and `supported_filter_versions`, so mixed-era rows are inspectable before an operator applies or updates them. When a selected custom view's `filter_version` is not supported by the current build, Waterline still returns the saved-view payload but marks `visibility_filters.saved_view_applied = false` and echoes the warning under `visibility_filters.saved_view_warning`; the list falls back to any direct query-string filters instead of silently pretending the outdated saved filters still applied. Updating that saved view rewrites it onto the current filter contract version. Current Waterline builds consume the shared definition plus the list route's echoed `visibility_filters.definition` to render the list-screen filter editor instead of keeping a separate hard-coded field schema in the browser, including select controls for bounded fields such as `status`, `status_bucket`, `closed_reason`, `wait_kind`, `repair_blocked_reason`, `declared_entry_mode`, and `declared_contract_source` plus booleans such as `repair_attention`, `task_problem`, `is_current_run`, `continue_as_new_recommended`, `declared_contract_backfill_needed`, and `declared_contract_backfill_available`. The same echoed definition now also exposes searchable `business_key` and `labels` metadata separately from returned-only `memo`, so Waterline can tell operators exactly which visibility metadata is indexed and saved-view-compatible before they try to save or share a view. The `repair_blocked_reason` option catalog now also carries the operator-facing description, severity tone, and `badge_visible` hint that Waterline uses for repair-triage badges, and `repair_attention` turns that same badge-visible subset into one durable/searchable saved-view filter, so the browser no longer has to keep its own reason map or hard-code a list of actionable reason codes. Current list rows use the same command-contract fields for fast triage badges such as compatibility-entry, contract-pending, contract-blocked, workflow-task-problem, and repair-blocked states before an operator opens selected-run detail. `WATERLINE_SAVED_VIEW_SCOPE` partitions saved views by app, environment, tenant, or operator namespace when several installs share one database. Waterline also returns system defaults such as `system:running`, `system:running-task-problems`, and `system:running-repair-blocked`; the repair-blocked view applies `repair_attention = true`, while the task-problems view applies `task_problem = true`, so operators can keep stable fleet views for badge-visible repair blockers and for selected runs with replay-blocked, missing, or repeatedly unhealthy workflow-task transport. Custom views are stored in the `waterline_saved_views` table, and the list screen can now save, update, and delete those custom views while showing the currently applied filter badges. Saving or updating a custom view now persists the effective applied filter set after any selected saved-view overlay, so operators do not accidentally drop the saved portion of the current view when refining or renaming it. Because `repair_attention`, `repair_blocked_reason`, `task_problem`, `declared_entry_mode`, and the command-contract backfill booleans are part of that same contract, operators can save repeatable views for repair-blocked drift, `unsupported_history`, workflow-task problem triage, compatibility-entry runs, loadable command-contract cleanup, or blocked command-contract normalization without rebuilding those filters by hand each time. Extra query filters on a saved-view URL refine the saved view for that request.
+A saved view records `name`, `bucket`, `scope`, `shared`, `filter_version`, and normalized `filters` using the workflow v2 visibility filter contract. `GET /waterline/api/saved-views?bucket=...` now also returns `filter_definition`, `supported_filter_versions`, and `version_evolution` so operator clients can render the same current field contract they save against, inspect deprecation status, and understand upgrade policy, even if no custom views exist yet. Each saved-view payload echoes `filter_version_supported`, `filter_version_deprecated`, `filter_version_status`, `filter_version_message`, `current_filter_version`, `minimum_supported_filter_version`, and `supported_filter_versions`, so mixed-era rows are inspectable before an operator applies or updates them. When `filter_version_deprecated` is `true`, the saved view is still loadable but should be updated to the current version; the `filter_version_message` explains the recommended action. When a selected custom view's `filter_version` is not supported by the current build, Waterline still returns the saved-view payload but marks `visibility_filters.saved_view_applied = false` and echoes the warning under `visibility_filters.saved_view_warning`; the list falls back to any direct query-string filters instead of silently pretending the outdated saved filters still applied. Updating that saved view rewrites it onto the current filter contract version. Current Waterline builds consume the shared definition plus the list route's echoed `visibility_filters.definition` to render the list-screen filter editor instead of keeping a separate hard-coded field schema in the browser, including select controls for bounded fields such as `status`, `status_bucket`, `closed_reason`, `wait_kind`, `repair_blocked_reason`, `declared_entry_mode`, and `declared_contract_source` plus booleans such as `repair_attention`, `task_problem`, `is_current_run`, `continue_as_new_recommended`, `declared_contract_backfill_needed`, and `declared_contract_backfill_available`. The same echoed definition now also exposes searchable `business_key`, `labels`, and `search_attributes` metadata separately from returned-only `memo`, so Waterline can tell operators exactly which visibility metadata is indexed and saved-view-compatible before they try to save or share a view. The `repair_blocked_reason` option catalog now also carries the operator-facing description, severity tone, and `badge_visible` hint that Waterline uses for repair-triage badges, and `repair_attention` turns that same badge-visible subset into one durable/searchable saved-view filter, so the browser no longer has to keep its own reason map or hard-code a list of actionable reason codes. Current list rows use the same command-contract fields for fast triage badges such as compatibility-entry, contract-pending, contract-blocked, workflow-task-problem, and repair-blocked states before an operator opens selected-run detail. `WATERLINE_SAVED_VIEW_SCOPE` partitions saved views by app, environment, tenant, or operator namespace when several installs share one database. Waterline also returns system defaults such as `system:running`, `system:running-task-problems`, and `system:running-repair-blocked`; the repair-blocked view applies `repair_attention = true`, while the task-problems view applies `task_problem = true`, so operators can keep stable fleet views for badge-visible repair blockers and for selected runs with replay-blocked, missing, or repeatedly unhealthy workflow-task transport. Custom views are stored in the `waterline_saved_views` table, and the list screen can now save, update, and delete those custom views while showing the currently applied filter badges. Saving or updating a custom view now persists the effective applied filter set after any selected saved-view overlay, so operators do not accidentally drop the saved portion of the current view when refining or renaming it. Because `repair_attention`, `repair_blocked_reason`, `task_problem`, `declared_entry_mode`, and the command-contract backfill booleans are part of that same contract, operators can save repeatable views for repair-blocked drift, `unsupported_history`, workflow-task problem triage, compatibility-entry runs, loadable command-contract cleanup, or blocked command-contract normalization without rebuilding those filters by hand each time. Extra query filters on a saved-view URL refine the saved view for that request.
 
 Query, Signal, and Update now sit on that same operator surface. Waterline shows Query only when `can_query = true` and the selected run exposes at least one `declared_query_targets[*].name`; unlike the mutating controls, that read-only query action can still stay available on historical or already-closed selected runs too. When durable query targets exist but selected-run detail reports `can_query = false`, Waterline keeps the declared targets visible but hides query execution, with `query_blocked_reason` explaining why. It shows Signal only when `can_signal = true` and the selected run exposes at least one `declared_signal_targets[*].name`. It shows Update only when `can_update = true` and the selected run exposes at least one `declared_update_targets[*].name`. The UI also shows `declared_contract_source`, `declared_contract_backfill_needed`, and `declared_contract_backfill_available` so operators can tell whether those targets came from durable `WorkflowStarted` history, a live-definition fallback, or no currently authoritative contract, and whether the current build can still normalize the preview-era snapshot. Compatible selected-run detail and history-export reads now persist loadable preview-era command-contract snapshots automatically, alongside the existing compatible query, signal, and update intake paths, and background repair/watchdog passes now keep draining loadable untouched runs in throttled batches. For untouched runs, use `php artisan workflow:v2:repair-pass` to force the next batch immediately, `php artisan workflow:v2:rebuild-projections --needs-rebuild --prune-stale` to sweep loadable preview-era command contracts alongside selected-run projection drift, or `php artisan workflow:v2:backfill-command-contracts --dry-run` and then the same command without `--dry-run` for a targeted contract-only pass before relying on them after refactors or class moves. When `declared_contract_backfill_needed = true` but `declared_contract_backfill_available = false`, the current build can still surface any remaining target names or parameter fragments, but that state is compatibility-only until a durable snapshot is persisted. Named query arguments and named JSON/object signal or update payloads reject when the missing durable contract is required, and query or update execution still blocks when replay needs an unavailable workflow definition. Each normalized target row carries the durable public target `name`, a `parameters` array when the run snapped a contract for that target, and `has_contract` so operator clients can distinguish contract-backed targets from bare declared names without hiding the latter. When a contract exists, Waterline now seeds the operator JSON editor from declared defaults plus type-aware primitive placeholders instead of filling every required scalar slot with `null`; rejected commands still surface durable `validation_errors`.