@pgflow/dsl 0.9.1 → 0.11.0

package/dist/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @pgflow/dsl
 
+## 0.11.0
+
+## 0.10.0
+
+### Patch Changes
+
+- 0b84bb0: Add automatic flow compilation at worker startup. Workers now call ensure_flow_compiled to verify flows are up-to-date. In development, mismatched flows are recompiled automatically. In production, mismatches cause errors. Use ensureCompiledOnStartup: false to opt-out.
+
 ## 0.9.1
 
 ### Patch Changes

package/dist/flow-shape.d.ts

@@ -0,0 +1,81 @@
+import { AnyFlow } from './dsl.js';
+/**
+ * Step-level options that can be included in the shape for creation,
+ * but are NOT compared during shape comparison (runtime tunable).
+ */
+export interface StepShapeOptions {
+    maxAttempts?: number;
+    baseDelay?: number;
+    timeout?: number;
+    startDelay?: number;
+}
+/**
+ * Flow-level options that can be included in the shape for creation,
+ * but are NOT compared during shape comparison (runtime tunable).
+ */
+export interface FlowShapeOptions {
+    maxAttempts?: number;
+    baseDelay?: number;
+    timeout?: number;
+}
+/**
+ * StepShape captures the structural definition of a step for drift detection.
+ *
+ * The `options` field is included for flow creation but NOT compared during
+ * shape comparison. Options can be tuned at runtime via SQL without
+ * requiring recompilation. See: /deploy/tune-flow-config/
+ */
+export interface StepShape {
+    slug: string;
+    stepType: 'single' | 'map';
+    dependencies: string[];
+    options?: StepShapeOptions;
+}
+/**
+ * FlowShape captures the structural definition of a flow for drift detection.
+ *
+ * This represents the DAG topology - which steps exist, their types, and how
+ * they connect via dependencies.
+ *
+ * The `options` field is included for flow creation but NOT compared during
+ * shape comparison. Options can be tuned at runtime via SQL without recompilation.
+ *
+ * Note: flowSlug is intentionally excluded - it's an identifier, not structural
+ * data. The slug comes from context (URL, registry lookup, function parameter).
+ */
+export interface FlowShape {
+    steps: StepShape[];
+    options?: FlowShapeOptions;
+}
+/**
+ * Result of comparing two FlowShapes.
+ */
+export interface ShapeComparisonResult {
+    match: boolean;
+    differences: string[];
+}
+/**
+ * Extracts a FlowShape from a Flow object.
+ * The shape captures structural information needed for drift detection,
+ * plus options for flow creation.
+ *
+ * Options are included in the shape for proper flow/step creation, but
+ * are NOT compared during shape comparison (they're runtime tunable).
+ *
+ * @param flow - The Flow object to extract shape from
+ * @returns A FlowShape representing the flow's structure and options
+ */
+export declare function extractFlowShape(flow: AnyFlow): FlowShape;
+/**
+ * Compares two FlowShapes and returns detailed differences.
+ * Used by ControlPlane for Layer 1 comparison (Worker vs ControlPlane).
+ *
+ * Only compares structural aspects (steps, types, dependencies).
+ * Runtime options are not compared as they can be tuned independently.
+ *
+ * @param a - First FlowShape (typically from worker)
+ * @param b - Second FlowShape (typically from ControlPlane or database)
+ * @returns ShapeComparisonResult with match status and list of differences
+ */
+export declare function compareFlowShapes(a: FlowShape, b: FlowShape): ShapeComparisonResult;
+//# sourceMappingURL=flow-shape.d.ts.map

package/dist/flow-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-shape.d.ts","sourceRoot":"","sources":["../src/flow-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAMnC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAwCzD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,SAAS,EACZ,CAAC,EAAE,SAAS,GACX,qBAAqB,CA6BvB"}

package/dist/flow-shape.js

@@ -0,0 +1,119 @@
+// ========================
+// SHAPE EXTRACTION
+// ========================
+/**
+ * Checks if an options object has any defined (non-undefined) values.
+ */
+function hasDefinedOptions(options) {
+    return Object.values(options).some((v) => v !== undefined);
+}
+/**
+ * Filters out undefined values from an options object.
+ * Returns only the keys with defined values.
+ */
+function filterDefinedOptions(options) {
+    return Object.fromEntries(Object.entries(options).filter(([_, v]) => v !== undefined));
+}
+/**
+ * Extracts a FlowShape from a Flow object.
+ * The shape captures structural information needed for drift detection,
+ * plus options for flow creation.
+ *
+ * Options are included in the shape for proper flow/step creation, but
+ * are NOT compared during shape comparison (they're runtime tunable).
+ *
+ * @param flow - The Flow object to extract shape from
+ * @returns A FlowShape representing the flow's structure and options
+ */
+export function extractFlowShape(flow) {
+    const steps = flow.stepOrder.map((stepSlug) => {
+        const stepDef = flow.getStepDefinition(stepSlug);
+        const stepShape = {
+            slug: stepSlug,
+            stepType: stepDef.stepType ?? 'single',
+            // Sort dependencies alphabetically for deterministic comparison
+            dependencies: [...stepDef.dependencies].sort(),
+        };
+        // Only include options if at least one is defined
+        const stepOptions = {
+            maxAttempts: stepDef.options.maxAttempts,
+            baseDelay: stepDef.options.baseDelay,
+            timeout: stepDef.options.timeout,
+            startDelay: stepDef.options.startDelay,
+        };
+        if (hasDefinedOptions(stepOptions)) {
+            stepShape.options = filterDefinedOptions(stepOptions);
+        }
+        return stepShape;
+    });
+    const shape = { steps };
+    // Only include flow options if at least one is defined
+    const flowOptions = {
+        maxAttempts: flow.options.maxAttempts,
+        baseDelay: flow.options.baseDelay,
+        timeout: flow.options.timeout,
+    };
+    if (hasDefinedOptions(flowOptions)) {
+        shape.options = filterDefinedOptions(flowOptions);
+    }
+    return shape;
+}
+// ========================
+// SHAPE COMPARISON
+// ========================
+/**
+ * Compares two FlowShapes and returns detailed differences.
+ * Used by ControlPlane for Layer 1 comparison (Worker vs ControlPlane).
+ *
+ * Only compares structural aspects (steps, types, dependencies).
+ * Runtime options are not compared as they can be tuned independently.
+ *
+ * @param a - First FlowShape (typically from worker)
+ * @param b - Second FlowShape (typically from ControlPlane or database)
+ * @returns ShapeComparisonResult with match status and list of differences
+ */
+export function compareFlowShapes(a, b) {
+    const differences = [];
+    // Compare step counts
+    if (a.steps.length !== b.steps.length) {
+        differences.push(`Step count differs: ${a.steps.length} vs ${b.steps.length}`);
+    }
+    // Compare steps by index (order matters)
+    const maxLen = Math.max(a.steps.length, b.steps.length);
+    for (let i = 0; i < maxLen; i++) {
+        const aStep = a.steps[i];
+        const bStep = b.steps[i];
+        if (!aStep) {
+            differences.push(`Step at index ${i}: missing in first shape (second has '${bStep.slug}')`);
+        }
+        else if (!bStep) {
+            differences.push(`Step at index ${i}: missing in second shape (first has '${aStep.slug}')`);
+        }
+        else {
+            compareSteps(aStep, bStep, i, differences);
+        }
+    }
+    return {
+        match: differences.length === 0,
+        differences,
+    };
+}
+/**
+ * Compares two steps at the same index and adds differences to the list.
+ */
+function compareSteps(a, b, index, differences) {
+    // Compare slug (order matters, so slugs must match at same index)
+    if (a.slug !== b.slug) {
+        differences.push(`Step at index ${index}: slug differs '${a.slug}' vs '${b.slug}'`);
+    }
+    // Compare step type
+    if (a.stepType !== b.stepType) {
+        differences.push(`Step at index ${index}: type differs '${a.stepType}' vs '${b.stepType}'`);
+    }
+    // Compare dependencies (already sorted)
+    const aDeps = a.dependencies.join(',');
+    const bDeps = b.dependencies.join(',');
+    if (aDeps !== bDeps) {
+        differences.push(`Step at index ${index}: dependencies differ [${a.dependencies.join(', ')}] vs [${b.dependencies.join(', ')}]`);
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './dsl.js';
 export * from './compile-flow.js';
+export * from './flow-shape.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export * from './dsl.js';
 export * from './compile-flow.js';
+export * from './flow-shape.js';

package/dist/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@pgflow/dsl",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pgflow-dev/pgflow",
+    "directory": "pkgs/dsl"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@pgflow/dsl",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pgflow-dev/pgflow",
+    "directory": "pkgs/dsl"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",