deploy: eec6e09

Author: github-actions[bot]

2.0/llms-full.txt

@@ -5327,6 +5327,11 @@ Those overrides are not limited to reads or projection rebuilds. `WorkflowStub::
 
 Keep custom subclasses schema-compatible with the built-in models. If a subclass also changes table names or other Eloquent conventions that the package models normally infer, override the affected relations on that subclass as well so `currentRun()`, `runs()`, and similar lookups stay aligned with your custom schema.
 
+See the [Customization Matrix](./customization-matrix.md) for the frozen v2
+support contract, including which overrides are safe as inherited subclasses,
+which ones need explicit relation overrides, and how serializer, repository,
+health, import, migration, and write-side behavior fit together.
+
 ## Payload Codec
 
 v2 uses `avro` for new workflow payloads:
@@ -5691,12 +5696,168 @@ To ensure that your activities run on the same server so that they can share dat
 
 In order to run a queue worker that only processes the `my_dedicated_queue` queue, you can use the `php artisan queue:work --queue=my_dedicated_queue` command. Alternatively, you can use Laravel Horizon to manage your queues. Horizon is a queue manager that provides a dashboard for monitoring the status of your queues and workers.
 
+<!-- Source: docs/configuration/customization-matrix.md -->
+
+# Customization Matrix
+
+This page freezes the supported Durable Workflow v2 customization contract.
+Use it when you need to move v2 durable models onto a different connection,
+swap model subclasses, replace the PHP operator-observability repository, or
+decide whether an older serializer setting is still valid during migration.
+
+## Supported override matrix
+
+| Surface | Supported contract | Notes |
+| --- | --- | --- |
+| `workflows.v2.instance_model` with a schema-compatible subclass that keeps the basename `WorkflowInstance` | Supported | Use this shape when you only need a different connection, casts, or app namespace. The inherited relations keep the package's `workflow_instance_id` foreign-key contract. |
+| `workflows.v2.instance_model` with a table-swapped or basename-changing subclass | Supported with explicit relation overrides | Override `runs()`, `commands()`, and `updates()` so they keep `workflow_instance_id`. The package now validates this at boot and rejects inherited relation inference that would change those keys. `currentRun()` already pins `current_run_id` explicitly and does not need an override. |
+| Other `workflows.v2.*_model` overrides (`run_model`, `task_model`, `history_event_model`, projections, schedules, activity rows, failures, messages, memos, search attributes, child calls) | Supported for schema-compatible subclasses | Keep the package column names, primary keys, and foreign keys. These relations already pin the keys they use, so table-swapped subclasses can stay on the inherited relation methods when the schema stays compatible. |
+| Custom table names plus custom foreign-key column names | Unsupported | The v2 runtime and operator surfaces assume the package column and key names. If you change them, you are outside the supported contract. |
+| `OperatorObservabilityRepository` replacement | Supported by container binding | Bind your implementation to `Workflow\V2\Contracts\OperatorObservabilityRepository`. This is a PHP runtime integration contract for Waterline and `WorkflowStub::historyExport()`, not a stable cross-language API. The repository receives package model objects. |
+| `serializer` | Supported only for `avro` and legacy drain/import codecs | New v2 runs always use Avro semantics. `workflow-serializer-y` and `workflow-serializer-base64` remain valid only for finishing or importing v1 history that still needs PHP-native decoding. Custom serializer classes from v1 are unsupported in v2. |
+| Health and doctor diagnostics | Supported | `php artisan workflow:v2:doctor` and Waterline v2 health/stats reflect the configured model classes and flag stale serializer settings as migration debt. |
+| Package migrations on a non-default connection | Supported with published migrations | Auto-loaded package migrations run on Laravel's default connection. If your durable models use another connection, publish the migrations and set the migration `$connection` explicitly. |
+| Core write-side runtime (`WorkflowStub::make()`, `load()`, task creation, current-run resolution) | Supported through the configured durable models | The runtime honors the configured `instance_model`, `run_model`, and `task_model`. Keep write-side tables schema-compatible with the package columns and keys. |
+
+## Exact v2 model keys
+
+The published `workflows.php` config exposes these durable model keys under
+`workflows.v2`:
+
+- `instance_model`
+- `run_model`
+- `history_event_model`
+- `task_model`
+- `command_model`
+- `link_model`
+- `activity_execution_model`
+- `activity_attempt_model`
+- `timer_model`
+- `failure_model`
+- `run_summary_model`
+- `run_wait_model`
+- `run_timeline_entry_model`
+- `run_timer_entry_model`
+- `run_lineage_entry_model`
+- `schedule_model`
+- `schedule_history_event_model`
+
+Use subclasses of the package models for those keys. Keep the package's column
+names and foreign keys unless a page in this docs set says otherwise.
+
+## Instance-model override rule
+
+The only current v2 override that needs extra relation work is
+`workflows.v2.instance_model` when your subclass changes the inferred foreign
+key away from `workflow_instance_id`.
+
+Typical safe example:
+
+```php
+namespace App\Models\V2;
+
+use Workflow\V2\Models\WorkflowInstance as BaseWorkflowInstance;
+
+final class WorkflowInstance extends BaseWorkflowInstance
+{
+    protected $connection = 'workflow';
+}
+```
+
+Because the subclass basename is still `WorkflowInstance`, Eloquent keeps the
+same inferred foreign key and the inherited relations remain aligned.
+
+If you use a different basename or a table-swapped storage model, override the
+affected relations explicitly:
+
+```php
+namespace App\Workflow\Storage;
+
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Workflow\V2\Models\WorkflowCommand;
+use Workflow\V2\Models\WorkflowInstance as BaseWorkflowInstance;
+use Workflow\V2\Models\WorkflowRun;
+use Workflow\V2\Models\WorkflowUpdate;
+use Workflow\V2\Support\ConfiguredV2Models;
+
+final class TenantWorkflowInstance extends BaseWorkflowInstance
+{
+    protected $table = 'tenant_workflow_instances';
+
+    public function runs(): HasMany
+    {
+        return $this->hasMany(
+            ConfiguredV2Models::resolve('run_model', WorkflowRun::class),
+            'workflow_instance_id',
+        );
+    }
+
+    public function commands(): HasMany
+    {
+        return $this->hasMany(
+            ConfiguredV2Models::resolve('command_model', WorkflowCommand::class),
+            'workflow_instance_id',
+        )->oldest('created_at');
+    }
+
+    public function updates(): HasMany
+    {
+        return $this->hasMany(
+            ConfiguredV2Models::resolve('update_model', WorkflowUpdate::class),
+            'workflow_instance_id',
+        )
+            ->orderBy('command_sequence')
+            ->oldest('accepted_at')
+            ->oldest('created_at')
+            ->oldest('id');
+    }
+}
+```
+
+If those overrides are missing, package boot now fails fast instead of letting
+the app drift onto inferred keys such as
+`tenant_workflow_instance_id` or `custom_workflow_instance_id`.
+
+## Serializer, import, and health rules
+
+- Keep `serializer = 'avro'` for new v2 work.
+- Use legacy codecs only while draining or importing v1 history that still
+  needs PHP-native payload decoding.
+- Do not point v2 at removed custom serializer classes from v1.
+- Run `php artisan workflow:v2:doctor` after upgrades and config changes. It is
+  the diagnostic surface that flags legacy serializer settings and other boot
+  readiness problems.
+- Treat Waterline v2 health and stats as the operator-facing view of the same
+  durable model configuration.
+
+## Migration and write-side rules
+
+- The normal path is auto-loaded package migrations on the default connection.
+- If your durable models use another connection, publish the migrations and set
+  the migration `$connection` so `php artisan migrate` targets the same
+  database as your configured model subclasses.
+- Keep the package table names, primary keys, and foreign keys on every model
+  that participates in the runtime write path.
+- The write path is not read-only customization: starts, loads, current-run
+  resolution, and task execution all use the configured durable models.
+
+## Related Guides
+
+- [Publishing Config](./publishing-config.md)
+- [Database Connection](./database-connection.md)
+- [Migration Guide](../migration.md)
+- [Monitoring](../monitoring.md)
+
 <!-- Source: docs/configuration/database-connection.md -->
 
 # Database Connection
 
 Here is an overview of the steps needed to customize the database connection used for the workflow v2 durable models. This is *only* required if you want to use a different database connection than the default connection you specified for your Laravel application.
 
+For the full v2 override contract, including table-swapped subclasses,
+serializer rules, repository replacement, health diagnostics, and migration
+expectations, see the [Customization Matrix](./customization-matrix.md).
+
 1. Create classes in your app models directory that extend the base v2 model classes
 2. Set the desired `$connection` option in each class
 3. Publish the workflow config file
@@ -5753,6 +5914,11 @@ Publish the workflow config file and update the `workflows.v2.*_model` bindings
 
 The package resolves models through `Workflow\V2\Support\ConfiguredV2Models`, so any relation or query that hits a v2 model will transparently pick up the configured connection.
 
+If you move beyond schema-compatible subclasses and change the inferred foreign
+key of your custom `instance_model`, the package now validates that the
+`runs()`, `commands()`, and `updates()` relations were overridden explicitly at
+boot.
+
 ## Migrations
 
 Workflow migrations are auto-loaded from the package (`WorkflowServiceProvider::loadMigrationsFrom`) and run against the default database connection. When you route the v2 tables at a non-default connection, publish the migrations with `php artisan vendor:publish --tag=migrations` and set `protected $connection = 'mysql';` on each published migration class so `php artisan migrate` runs them against the correct database.