Fix missing realtime broadcasts for step:started and step:completed events (#306)

## Summary

Fixes critical bug where clients were not receiving `step:started` and `step:completed` realtime events. PostgreSQL's query optimizer was eliminating CTEs containing `realtime.send()` calls because they weren't referenced by subsequent operations.

## Root Cause

PostgreSQL eliminates unreferenced CTEs during query optimization. The CTEs containing `realtime.send()` calls existed in the code but were optimized away because they weren't referenced by the final RETURN statement or subsequent operations.

## Solution

Moved `realtime.send()` calls directly into RETURNING clauses of UPDATE statements, ensuring they execute atomically with state changes and cannot be optimized away.

## What's Fixed

- `step:started` events now broadcast when steps begin executing
- `step:completed` events now broadcast for empty map steps
- `step:completed` events now broadcast for cascade completions
- Dependent steps can now properly track when upstream steps start

## Changes

### Core Package (@pgflow/core)

- `start_ready_steps()`: Broadcasts `step:started` and `step:completed` events in RETURNING clauses
- `cascade_complete_taskless_steps()`: Broadcasts `step:completed` events atomically with cascade completion
- `complete_task()`: Added PERFORM statements for `run:failed` and `step:failed` broadcasts

### Client Package (@pgflow/client)

- Added `applySnapshot()` methods to FlowRun and FlowStep for proper initial state hydration without event emission
- Enhanced test coverage for realtime event lifecycles with comprehensive matchers
- Added edge case documentation for `waitForStatus()` with empty map steps and abort signals

### Testing

- Added comprehensive realtime event lifecycle tests covering event emission, ordering, sequences, and payload validation
- Added edge case tests for empty map steps and cascade completions

### Documentation

- Updated abort signal support examples in `waitForStatus()`
- Documented empty map step behavior (skip `step:started`, go directly to `step:completed`)
- Added edge case documentation for `waitForStatus()` timing

## Breaking Changes

None

## Migration

This release includes database migrations. Users should follow the [update guide](/deploy/update-pgflow/) after upgrading packages.

Author: jumski

pkgs/core/supabase/tests/cascade_complete_taskless_steps/cascade-tests.md

@@ -221,6 +221,46 @@ if (result.status === FlowRunStatus.Failed) {
 }
 ```
 
+## Canceling Wait Operations
+
+Use `AbortSignal` to cancel waiting operations when needed:
+
+```typescript
+const controller = new AbortController();
+
+// Start waiting with abort signal
+const waitPromise = run.waitForStatus(FlowRunStatus.Completed, {
+  timeoutMs: 60000,
+  signal: controller.signal,
+});
+
+// Cancel if user navigates away (browser example)
+window.addEventListener('beforeunload', () => {
+  controller.abort();
+});
+
+// Or cancel on user action
+document.getElementById('cancel-btn')?.addEventListener('click', () => {
+  controller.abort();
+});
+
+try {
+  await waitPromise;
+  console.log('Workflow completed:', run.output);
+} catch (error) {
+  if (error.message.includes('Aborted')) {
+    console.log('User canceled the operation');
+  } else {
+    throw error; // Re-throw other errors
+  }
+}
+```
+
+This is particularly useful in interactive applications where users might:
+- Navigate away before workflow completion
+- Cancel long-running operations
+- Switch between different workflows
+
 ## Resource Cleanup
 
 :::caution

pkgs/website/src/content/docs/build/starting-flows/typescript-client.mdx

@@ -0,0 +1,40 @@
+---
+draft: false
+title: 'pgflow 0.7.2: Fix Missing Realtime Broadcasts for Step Events'
+description: 'Critical fix for missing step:started and step:completed realtime events'
+date: 2025-01-04
+authors:
+  - jumski
+tags:
+  - bugfix
+  - realtime
+  - client
+  - core
+featured: true
+---
+
+import { Aside } from "@astrojs/starlight/components";
+
+pgflow 0.7.2 fixes missing realtime broadcasts that prevented clients from receiving `step:started` and `step:completed` events. PostgreSQL's query optimizer was eliminating CTEs containing `realtime.send()` calls because they weren't referenced by subsequent operations.
+
+## What's Fixed
+
+- `step:started` events now broadcast when steps begin executing
+- `step:completed` events now broadcast for empty map steps
+- `step:completed` events now broadcast for cascade completions
+- Client applySnapshot() methods added for proper initial state hydration without event emission
+
+## Additional Changes
+
+- Enhanced test coverage for realtime event lifecycles
+- Documentation updates for abort signal support and empty map step behavior
+
+## Upgrading
+
+<Aside type="note" title="Migration Required">
+This release includes database migrations. See the [update guide](/deploy/update-pgflow/) for instructions.
+</Aside>
+
+---
+
+**Questions or issues?** Join our [Discord community](https://www.pgflow.dev/discord/) or [open an issue on GitHub](https://github.com/pgflow-dev/pgflow/issues).