@pgflow/core 0.0.5 → 0.0.7

package/{CHANGELOG.md → dist/CHANGELOG.md}

@@ -1,5 +1,11 @@
 # @pgflow/core
 
+## 0.0.6
+
+### Patch Changes
+
+- @pgflow/dsl@0.0.6
+
 ## 0.0.5
 
 ### Patch Changes

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@pgflow/core",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "license": "AGPL-3.0",
   "type": "module",
   "main": "./dist/index.js",
-  "typings": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "supabase/migrations/*.sql"
+  ],
   "private": false,
   "exports": {
     "./package.json": "./package.json",
@@ -13,15 +18,13 @@
       "import": "./dist/index.js"
     }
   },
-  "types": "./dist/index.d.ts",
-  "module": "./dist/index.js",
   "devDependencies": {
     "supabase": "^2.6.8",
     "vitest": "*"
   },
   "dependencies": {
     "postgres": "^3.4.5",
-    "@pgflow/dsl": "^0.0.5"
+    "@pgflow/dsl": "^0.0.7"
   },
   "publishConfig": {
     "access": "public"

package/__tests__/mocks/index.ts

@@ -1 +0,0 @@
-export * from './postgres.ts';

package/__tests__/mocks/postgres.ts

@@ -1,37 +0,0 @@
-import { vi } from 'vitest';
-
-/**
- * Mock implementation for the postgres module
- * This prevents real database connections during tests
- */
-export function setupPostgresMock() {
-  // Create a properly typed SQL client with methods
-  type SqlClient = {
-    (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
-    json: (data: unknown) => string;
-    begin: () => Promise<void>;
-    commit: () => Promise<void>;
-    rollback: () => Promise<void>;
-    end: () => Promise<void>;
-  };
-
-  // Create the main postgres function that returns the SQL client
-  const sql = vi.fn(() => {
-    // Create a complete mock SQL client with all required methods
-    const sqlClient = Object.assign(
-      vi.fn(() => Promise.resolve(['empty response'])),
-      {
-        json: vi.fn((data: unknown) => JSON.stringify(data)),
-        begin: vi.fn(() => Promise.resolve()),
-        commit: vi.fn(() => Promise.resolve()),
-        rollback: vi.fn(() => Promise.resolve()),
-        end: vi.fn(() => Promise.resolve()),
-      }
-    ) as SqlClient;
-
-    return sqlClient;
-  });
-
-  // Return an object with a default key since postgres is imported as a default export
-  return { default: sql };
-}

package/__tests__/types/PgflowSqlClient.test-d.ts

@@ -1,59 +0,0 @@
-import { describe, it, expectTypeOf, vi, beforeEach } from 'vitest';
-import { setupPostgresMock } from '../mocks/postgres.ts';
-
-// Mock the postgres module so that it never makes a real connection.
-// This must come before the postgres import
-vi.mock('postgres', () => {
-  return setupPostgresMock();
-});
-
-import { PgflowSqlClient } from '../../src/PgflowSqlClient.ts';
-import type { Json, StepTaskKey } from '../../src/types.ts';
-import postgres from 'postgres';
-import { Flow } from '@pgflow/dsl';
-
-describe('PgflowSqlClient Type Compatibility with Flow', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('should properly type IPgflowClient methods', () => {
-    // Arrange
-    const sql = postgres();
-    const flow = new Flow<{ url: string }>({ slug: 'test_flow' });
-    const client = new PgflowSqlClient<typeof flow>(sql);
-
-    // Check pollForTasks method types
-    expectTypeOf(client.pollForTasks).toBeFunction();
-    expectTypeOf(client.pollForTasks).parameters.toMatchTypeOf<
-      [string, number?, number?, number?, number?]
-    >();
-
-    // Check completeTask method types
-    expectTypeOf(client.completeTask).toBeFunction();
-    expectTypeOf(client.completeTask).parameters.toMatchTypeOf<
-      [StepTaskKey, Json?]
-    >();
-
-    // Check failTask method types
-    expectTypeOf(client.failTask).toBeFunction();
-    expectTypeOf(client.failTask).parameters.toMatchTypeOf<
-      [StepTaskKey, unknown]
-    >();
-  });
-
-  it('allows only valid Flow input', () => {
-    const sql = postgres();
-    const flow = new Flow<{ url: string }>({ slug: 'test_flow' });
-    const client = new PgflowSqlClient<typeof flow>(sql);
-
-    // @ts-expect-error - Flow expects { url: string } not a number
-    client.startFlow(flow, 23);
-
-    // @ts-expect-error - Flow expects { url: string }
-    client.startFlow(flow, { url: 23 });
-
-    // @ts-expect-error - Flow does not accept extraneous keys
-    client.startFlow(flow, { url: 'string', extraneousKey: 'value' });
-  });
-});

package/docs/options_for_flow_and_steps.md

@@ -1,75 +0,0 @@
-:::
-
-1. MVP will allow only 1:1 queue:flow mappings, because it simplifies a lot.
-   Queue is created when creating a flow, in pgflow.create_flow() function.
-
-2. No, we will start with either static delay or simple exponential and
-   I do not plan to expand on it further.
-
-   The backoff will be calculated by the retry attempts, that can be deducted
-   from pgmq's "read_ct" counter.
-
-   No need for jitter for now.
-
-3. **Execution Timeouts**
-   I'm not sure about flow timeouts, I think for MVP we should probably
-   skip them and I'm not even sure if I want to have them for the steps too.
-
-   I would be definitely adding them in future.
-
-4. We want everything to by statically typed in TypeScript, because the main
-   way to define flows would be to use TS DSL.
-
-   So a condition must be a JSON-serializable object that will get saved
-   in a JSONB column.
-
-   My initial idea for conditions was to just provide a JSON object that we
-   will use to perform containment check on the step inputs using @> operator.
-
-   I am considering expanding it to more robust condition, but they would need
-   to be defined in JSON-serializable way.
-
-   I do not want to have any SQL snippets in conditions, because I cannot
-   statically type them and they can fail at runtime.
-
-   No, conditions should probably only be able to reference step inputs.
-
-5. Yes it should be able to disable retries per step or override their params.
-   How those circuit breakers should work and what would be the benefit of them?
-   What is retry budget? Do we have a distributed system really? Everything
-   lives in a single postgres instance.
-
-6. No we do not want to support dependency resolution at runtime,
-   but conditions could be used to implement something similar.
-   Steps should not be able to add new steps during runtime,
-   but I plan to have fanout steps that will spawn either multiple tasks
-   or multiple subflows, one per the input array item.
-   Those are meant to be aggregated back to the output array when completed.
-
-   It's not for MVP tho!!
-
-### Cross-Cutting Concerns
-7. We will advise users to not put anything sensitive into flow options,
-   by writing docs and also not having handlers any ability to access the
-   step options.
-
-   We will provide a Context object that users can define in the Flow DSL,
-   that will be passed to the step handlers at runtime and will encourage
-   users to use this Context object to store sensitive data.
-
-8. What you mean by tracked metadata for options and options affecting metric?
-
-9. Versioning is a big problem for my project - I have few ideas how to solve
-   it (basically topologically sort graph and hash it to create a version hash).
-   But for MVP we definitely don't need versioning - users must take care of
-   this on their own by just creating new flows if they change the shape of
-   the flow. There is no way and will be no way to UPDATE flows.
-
-   Graph shape should be immutable after creation, but i'm not sure about
-   the options - maybe it would be a good idea to allow updating retry configs,
-   because only running the flows in production can allow users to gather
-   enough data to make educated decisions about those params.
-
-10. No modification for flows/steps at all, so easy.
-    
-:::

package/docs/pgflow-blob-reference-system.md

@@ -1,179 +0,0 @@
-# PgFlow Blob Reference System
-
-## Overview
-
-PgFlow needs an efficient way to handle large data outputs from workflow steps. The Blob Reference System provides a solution by separating large data payloads from workflow control information while maintaining a seamless developer experience.
-
-## How It Works
-
-### Core Concept
-
-When steps produce large outputs (e.g., HTML content from web scraping, binary data, large API responses), these outputs are stored separately in a dedicated blob storage table. The workflow state maintains references to these blobs rather than storing the actual large data.
-
-### Database Structure
-
-The system uses a dedicated table for blob storage:
-
-```sql
-CREATE TABLE pgflow.output_blobs (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  content JSONB NOT NULL,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-```
-
-### Worker Task Structure
-
-The `poll_for_tasks` function returns tasks with both regular inputs and blob references through a custom type:
-
-```sql
-CREATE TYPE pgflow.step_task_record AS (
-  flow_slug TEXT,
-  run_id UUID,
-  step_slug TEXT,
-  input JSONB,
-  blobs_refs JSONB
-);
-```
-
-This design provides a clean separation between:
-
-- `input`: Regular small data that can be directly included in the task
-- `blobs_refs`: References to large data stored separately in the blob table
-
-### Example Return Value
-
-A task returned by `poll_for_tasks` might look like:
-
-```json
-{
-  "flow_slug": "my_flow",
-  "run_id": "1234-5678-90ab-cdef",
-  "step_slug": "my_step",
-  "input": {
-    "run": "run input",
-    "dependency_a": "dependency_a output"
-  },
-  "blobs_refs": {
-    "dependency_b": "<uuid to the blob saved for dependency_b which returned binary data>"
-  }
-}
-```
-
-In this example:
-
-- `dependency_a` had a small output that's included directly in the `input` object
-- `dependency_b` had a large output (possibly binary data) that's stored as a blob, with only a reference included
-
-### Queue Efficiency
-
-A critical optimization in PgFlow is that the task queue only stores minimal task identification information:
-
-- flow_slug
-- run_id
-- step_slug
-- task_index
-
-This lightweight approach keeps queue messages small and efficient. When a worker picks up a task, it uses these identifiers to:
-
-1. Call `poll_for_tasks` to get the full task data
-2. Receive both the regular `input` and `blobs_refs` in a single query result
-3. Fetch the actual blob content for any referenced blobs
-4. Combine all data to form the complete input for the task handler
-
-## Implementation Flow
-
-### Task Creation
-
-1. When a step completes, its output is analyzed:
-
-   - Outputs below the size threshold remain in the regular output JSONB
-   - Large outputs are stored in the `pgflow.output_blobs` table with a unique ID
-
-2. The `start_ready_steps` function:
-   - Creates task entries with references to any large blob data
-   - Enqueues only the task identifiers (not the actual data) in the task queue
-
-### Task Execution
-
-1. Worker picks up the task identifier from the queue
-2. Worker calls `poll_for_tasks` to get the task details
-3. `poll_for_tasks` returns:
-   - The `input` object with regular data
-   - The `blobs_refs` object with references to any large data outputs
-4. Worker fetches blob content for any references in `blobs_refs`
-5. Worker assembles the complete input (combining regular data and blob data) for the task handler
-6. Task handler executes with the complete data, unaware of the blob reference system
-
-### Example Processing Flow
-
-For a web scraping workflow:
-
-1. `fetch-html` step returns a large HTML string (3MB)
-2. System detects the large output and:
-   - Stores HTML in `pgflow.output_blobs` with ID "abc-123"
-   - Records only the blob reference in the step's output
-3. When `parse-html` step is ready to run:
-   - Queue contains only the task identifier
-   - `poll_for_tasks` returns the task with:
-     ```json
-     {
-       "input": {
-         "run": { "url": "https://example.com" }
-       },
-       "blobs_refs": {
-         "fetch-html": "abc-123"
-       }
-     }
-     ```
-4. Worker:
-   - Detects the blob reference "abc-123" for "fetch-html"
-   - Fetches the actual HTML content from the blob table
-   - Provides the handler with complete input including the HTML content
-
-## Developer Experience
-
-From a workflow developer's perspective, the blob reference system is completely transparent:
-
-```typescript
-// Developer writes code as if all data is directly available
-const parseHtmlHandler: StepHandler<ParseInput, ParseOutput> = async (
-  input
-) => {
-  // input.dependencies["fetch-html"] contains the full HTML content
-  // (the blob reference was automatically resolved)
-  const html = input.dependencies['fetch-html'];
-
-  // Process the HTML...
-  const title = extractTitle(html);
-  const links = extractLinks(html);
-
-  return { title, links };
-};
-```
-
-The developer never needs to:
-
-- Manually resolve blob references
-- Check if data is a reference or actual content
-- Handle storage of large outputs differently
-
-## Benefits and Considerations
-
-### Benefits
-
-1. **Database Efficiency**: Large data is stored separately from workflow metadata
-2. **Queue Performance**: Queue messages remain small and consistent in size
-3. **Separation of Concerns**: Control flow data is separate from large payloads
-4. **Transparent to Developers**: No special code required to handle large data
-5. **Scalability**: Can handle arbitrary data sizes without affecting workflow system performance
-
-### Considerations
-
-1. **Query Optimization**: Ensure `poll_for_tasks` efficiently retrieves both regular data and blob references
-2. **Blob Lifecycle Management**: Implement cleanup for orphaned or expired blobs
-3. **Size Threshold Tuning**: Configure appropriate thresholds for when data should use blob storage
-
-## Conclusion
-
-The Blob Reference System in PgFlow provides an elegant solution for handling large data in workflows. By splitting task data into regular inputs and blob references, the system maintains efficient database usage and queue performance while providing a seamless experience for workflow developers. The design ensures that large data is handled appropriately without requiring developers to write special code for blob resolution or storage.

package/eslint.config.cjs

@@ -1,22 +0,0 @@
-const baseConfig = require('../../eslint.config.cjs');
-
-module.exports = [
-  ...baseConfig,
-  {
-    files: ['**/*.json'],
-    rules: {
-      '@nx/dependency-checks': [
-        'error',
-        {
-          ignoredFiles: [
-            '{projectRoot}/eslint.config.{js,cjs,mjs}',
-            '{projectRoot}/vite.config.{js,ts,mjs,mts}',
-          ],
-        },
-      ],
-    },
-    languageOptions: {
-      parser: require('jsonc-eslint-parser'),
-    },
-  },
-];

package/example-flow.mermaid

@@ -1,5 +0,0 @@
-graph LR
-      A[website] --> B[sentiment]
-      A --> C[summary]
-      B --> D[saveToDb]
-      C --> D

package/example-flow.svg

@@ -1 +0,0 @@
-<svg aria-roledescription="flowchart-v2" role="graphics-document document" viewBox="0 0 497.90625 174" style="max-width: 497.906px; background-color: white;" class="flowchart" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="100%" id="my-svg"><style>#my-svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#my-svg .error-icon{fill:#552222;}#my-svg .error-text{fill:#552222;stroke:#552222;}#my-svg .edge-thickness-normal{stroke-width:1px;}#my-svg .edge-thickness-thick{stroke-width:3.5px;}#my-svg .edge-pattern-solid{stroke-dasharray:0;}#my-svg .edge-thickness-invisible{stroke-width:0;fill:none;}#my-svg .edge-pattern-dashed{stroke-dasharray:3;}#my-svg .edge-pattern-dotted{stroke-dasharray:2;}#my-svg .marker{fill:#333333;stroke:#333333;}#my-svg .marker.cross{stroke:#333333;}#my-svg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#my-svg p{margin:0;}#my-svg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#my-svg .cluster-label text{fill:#333;}#my-svg .cluster-label span{color:#333;}#my-svg .cluster-label span p{background-color:transparent;}#my-svg .label text,#my-svg span{fill:#333;color:#333;}#my-svg .node rect,#my-svg .node circle,#my-svg .node ellipse,#my-svg .node polygon,#my-svg .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#my-svg .rough-node .label text,#my-svg .node .label text,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-anchor:middle;}#my-svg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#my-svg .rough-node .label,#my-svg .node .label,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-align:center;}#my-svg .node.clickable{cursor:pointer;}#my-svg .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#my-svg .arrowheadPath{fill:#333333;}#my-svg .edgePath .path{stroke:#333333;stroke-width:2.0px;}#my-svg .flowchart-link{stroke:#333333;fill:none;}#my-svg .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#my-svg .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#my-svg .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#my-svg .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#my-svg .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#my-svg .cluster text{fill:#333;}#my-svg .cluster span{color:#333;}#my-svg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#my-svg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#my-svg rect.text{fill:none;stroke-width:0;}#my-svg .icon-shape,#my-svg .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#my-svg .icon-shape p,#my-svg .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#my-svg .icon-shape rect,#my-svg .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#my-svg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}</style><g><marker orient="auto" markerHeight="8" markerWidth="8" markerUnits="userSpaceOnUse" refY="5" refX="5" viewBox="0 0 10 10" class="marker flowchart-v2" id="my-svg_flowchart-v2-pointEnd"><path style="stroke-width: 1; stroke-dasharray: 1, 0;" class="arrowMarkerPath" d="M 0 0 L 10 5 L 0 10 z"/></marker><marker orient="auto" markerHeight="8" markerWidth="8" markerUnits="userSpaceOnUse" refY="5" refX="4.5" viewBox="0 0 10 10" class="marker flowchart-v2" id="my-svg_flowchart-v2-pointStart"><path style="stroke-width: 1; stroke-dasharray: 1, 0;" class="arrowMarkerPath" d="M 0 5 L 10 10 L 10 0 z"/></marker><marker orient="auto" markerHeight="11" markerWidth="11" markerUnits="userSpaceOnUse" refY="5" refX="11" viewBox="0 0 10 10" class="marker flowchart-v2" id="my-svg_flowchart-v2-circleEnd"><circle style="stroke-width: 1; stroke-dasharray: 1, 0;" class="arrowMarkerPath" r="5" cy="5" cx="5"/></marker><marker orient="auto" markerHeight="11" markerWidth="11" markerUnits="userSpaceOnUse" refY="5" refX="-1" viewBox="0 0 10 10" class="marker flowchart-v2" id="my-svg_flowchart-v2-circleStart"><circle style="stroke-width: 1; stroke-dasharray: 1, 0;" class="arrowMarkerPath" r="5" cy="5" cx="5"/></marker><marker orient="auto" markerHeight="11" markerWidth="11" markerUnits="userSpaceOnUse" refY="5.2" refX="12" viewBox="0 0 11 11" class="marker cross flowchart-v2" id="my-svg_flowchart-v2-crossEnd"><path style="stroke-width: 2; stroke-dasharray: 1, 0;" class="arrowMarkerPath" d="M 1,1 l 9,9 M 10,1 l -9,9"/></marker><marker orient="auto" markerHeight="11" markerWidth="11" markerUnits="userSpaceOnUse" refY="5.2" refX="-1" viewBox="0 0 11 11" class="marker cross flowchart-v2" id="my-svg_flowchart-v2-crossStart"><path style="stroke-width: 2; stroke-dasharray: 1, 0;" class="arrowMarkerPath" d="M 1,1 l 9,9 M 10,1 l -9,9"/></marker><g class="root"><g class="clusters"/><g class="edgePaths"><path marker-end="url(#my-svg_flowchart-v2-pointEnd)" style="" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" id="L_A_B_0" d="M113.179,60L120.045,55.833C126.911,51.667,140.643,43.333,151.009,39.167C161.375,35,168.375,35,171.875,35L175.375,35"/><path marker-end="url(#my-svg_flowchart-v2-pointEnd)" style="" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" id="L_A_C_1" d="M113.179,114L120.045,118.167C126.911,122.333,140.643,130.667,151.308,134.833C161.974,139,169.573,139,173.372,139L177.172,139"/><path marker-end="url(#my-svg_flowchart-v2-pointEnd)" style="" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" id="L_B_D_2" d="M308.75,35L312.917,35C317.083,35,325.417,35,336.263,38.835C347.109,42.669,360.469,50.339,367.148,54.174L373.828,58.008"/><path marker-end="url(#my-svg_flowchart-v2-pointEnd)" style="" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" id="L_C_D_3" d="M306.953,139L311.419,139C315.885,139,324.818,139,335.964,135.165C347.109,131.331,360.469,123.661,367.148,119.826L373.828,115.992"/></g><g class="edgeLabels"><g class="edgeLabel"><g transform="translate(0, 0)" class="label"><foreignObject height="0" width="0"><div style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" class="labelBkg" xmlns="http://www.w3.org/1999/xhtml"><span class="edgeLabel"></span></div></foreignObject></g></g><g class="edgeLabel"><g transform="translate(0, 0)" class="label"><foreignObject height="0" width="0"><div style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" class="labelBkg" xmlns="http://www.w3.org/1999/xhtml"><span class="edgeLabel"></span></div></foreignObject></g></g><g class="edgeLabel"><g transform="translate(0, 0)" class="label"><foreignObject height="0" width="0"><div style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" class="labelBkg" xmlns="http://www.w3.org/1999/xhtml"><span class="edgeLabel"></span></div></foreignObject></g></g><g class="edgeLabel"><g transform="translate(0, 0)" class="label"><foreignObject height="0" width="0"><div style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" class="labelBkg" xmlns="http://www.w3.org/1999/xhtml"><span class="edgeLabel"></span></div></foreignObject></g></g></g><g class="nodes"><g transform="translate(68.6875, 87)" id="flowchart-A-0" class="node default"><rect height="54" width="121.375" y="-27" x="-60.6875" style="" class="basic label-container"/><g transform="translate(-30.6875, -12)" style="" class="label"><rect/><foreignObject height="24" width="61.375"><div style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" xmlns="http://www.w3.org/1999/xhtml"><span class="nodeLabel"><p>website</p></span></div></foreignObject></g></g><g transform="translate(244.0625, 35)" id="flowchart-B-1" class="node default"><rect height="54" width="129.375" y="-27" x="-64.6875" style="" class="basic label-container"/><g transform="translate(-34.6875, -12)" style="" class="label"><rect/><foreignObject height="24" width="69.375"><div style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" xmlns="http://www.w3.org/1999/xhtml"><span class="nodeLabel"><p>sentiment</p></span></div></foreignObject></g></g><g transform="translate(244.0625, 139)" id="flowchart-C-3" class="node default"><rect height="54" width="125.78125" y="-27" x="-62.890625" style="" class="basic label-container"/><g transform="translate(-32.890625, -12)" style="" class="label"><rect/><foreignObject height="24" width="65.78125"><div style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" xmlns="http://www.w3.org/1999/xhtml"><span class="nodeLabel"><p>summary</p></span></div></foreignObject></g></g><g transform="translate(424.328125, 87)" id="flowchart-D-5" class="node default"><rect height="54" width="131.15625" y="-27" x="-65.578125" style="" class="basic label-container"/><g transform="translate(-35.578125, -12)" style="" class="label"><rect/><foreignObject height="24" width="71.15625"><div style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;" xmlns="http://www.w3.org/1999/xhtml"><span class="nodeLabel"><p>saveToDb</p></span></div></foreignObject></g></g></g></g></g></svg>

package/flow-lifecycle.mermaid

@@ -1,83 +0,0 @@
-sequenceDiagram
-    participant Client
-    participant pgflow as pgflow SQL Core
-    participant PGMQ as PGMQ Queue
-    participant Worker as Edge Worker
-    participant Handler as Task Handler
-
-    Client->>pgflow: create_flow(...)
-    Client->>pgflow: add_step(...)
-    Client->>pgflow: start_flow(...)
-
-    activate pgflow
-    pgflow->>pgflow: Create run record
-    pgflow->>pgflow: Initialize step_states
-    pgflow->>pgflow: Create step_tasks for root steps
-    pgflow->>PGMQ: Enqueue message for root step task
-    pgflow-->>Client: Return run details
-    deactivate pgflow
-
-    Worker->>pgflow: poll_for_tasks(...)
-
-    activate pgflow
-    pgflow->>PGMQ: Get visible messages
-    PGMQ-->>pgflow: Return messages
-    pgflow->>pgflow: Increment attempts counter on task
-    pgflow->>pgflow: Build step input by combining run input & dependency outputs
-    pgflow-->>Worker: Return tasks with metadata and inputs
-    deactivate pgflow
-
-    Worker->>Worker: Find handler function for a task
-
-    note right of Worker: Task Execution
-
-    Worker->>Handler: Call handler function with task input
-
-    rect rgb(235, 255, 235)
-      note left of Handler: Task succeeds
-      activate Handler
-      Handler-->>Worker: Return result
-      deactivate Handler
-
-      Worker->>pgflow: complete_task(results)
-
-      activate pgflow
-      pgflow->>pgflow: Update task status to 'completed'
-      pgflow->>PGMQ: Archive message
-      pgflow->>pgflow: Update step_state to 'completed'
-      pgflow->>pgflow: Check & start dependent steps
-      pgflow->>PGMQ: Enqueue messages for ready dependent steps
-      pgflow->>pgflow: Decrement remaining_steps counter
-      pgflow->>pgflow: If all steps completed, mark run as 'completed'
-      pgflow-->>Worker: Confirmation
-      deactivate pgflow
-    end
-
-    rect rgb(250, 240, 240)
-      note left of Handler: Handler throws or exceeds timeout
-
-      activate Handler
-      Handler--xWorker: Throw exception or exceeds timeout
-      deactivate Handler
-      Worker->>pgflow: fail_task(error_message)
-
-      activate pgflow
-      pgflow->>pgflow: Check remaining retry attempts
-
-      rect rgb(240, 250, 240)
-        note right of pgflow: Retries remaining
-        pgflow->>PGMQ: Delay message visibility
-        PGMQ->>PGMQ: Message becomes visible
-        note right of Worker: Worker attempts execution again
-        Worker->>pgflow: poll_for_tasks(...)
-      end
-      rect rgb(255, 225, 225)
-        note right of pgflow: No retries remaining
-        pgflow->>pgflow: Mark task as 'failed'
-        pgflow->>pgflow: Mark step as 'failed'
-        pgflow->>pgflow: Mark run as 'failed'
-        pgflow->>PGMQ: Archive message
-        note right of pgflow: Permanent failure of a run
-      end
-      deactivate pgflow
-    end