feat: add ensure-compiled endpoint to control plane server

[jumski]

Add ensure-compiled endpoint to edge worker control plane

This PR adds a new endpoint to the edge worker control plane API: /flows/:slug/ensure-compiled. This endpoint allows clients to verify that a flow's compiled SQL matches its expected shape, or to recompile it if needed.

Key features:

• Adds authentication via an API key header
• Supports both "development" and "production" modes:
  • Development mode automatically recompiles flows when changes are detected
  • Production mode returns a 409 error when changes are detected (preventing unexpected changes)
• Returns detailed information about differences between the expected and actual flow shapes
• Integrates with a database SQL function for persistence

The endpoint returns different status codes based on the result:

• 200: Flow was verified, compiled, or recompiled successfully
• 409: Flow shape mismatch detected in production mode
• 400: Invalid request body
• 401: Authentication failed
• 404: Endpoint not configured
• 500: Database error

Comprehensive tests have been added to verify all functionality and edge cases.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6ed062f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[jumski]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: add secure local development detection for flow compilation #473
• refactor: use Supabase service role key for worker authentication #472
• feat: include options in FlowShape for proper flow creation #471
• feat: add ensure-compiled endpoint to control plane server #467 👈 (View in Graphite)
• feat: add ensure_flow_compiled function with dev/prod mode support #466
• feat: add flow compilation utilities for creating flows from JSON shapes #465
• feat: add SQL functions to compare and retrieve flow shapes #464
• Setup Worker Startup Compilation Phase 1 #463
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge:queue - adds this PR to the back of the merge queue
• hotfix:queue - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 6ed062f

Command	Status	Duration	Result
nx affected -t verify-exports --base=origin/mai...	✅ Succeeded	3s	View ↗
nx affected -t build --configuration=production...	✅ Succeeded	25s	View ↗
nx affected -t lint typecheck test --parallel -...	✅ Succeeded	3m 51s	View ↗
nx run edge-worker:e2e	✅ Succeeded	2m 37s	View ↗
nx run cli:e2e	✅ Succeeded	4s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-11-30 16:05:09 UTC

[graphite-app]

Critical: Accessing result.result on line 299 will throw a runtime error if the SQL query returns an empty array. The array destructuring const [result] = await options.sql... will set result to undefined if the array is empty, causing result.result to throw TypeError: Cannot read property 'result' of undefined.

While this is caught by the try-catch block and returns a 500 error, it produces a misleading error message. The code should explicitly check if a result was returned:

const results = await options.sql`
  SELECT pgflow.ensure_flow_compiled(
    ${flowSlug},
    ${JSON.stringify(shape)}::jsonb,
    ${mode}
  ) as result
`;

if (!results || results.length === 0 || !results[0]?.result) {
  return jsonResponse(
    {
      error: 'Database Error',
      message: 'No result returned from ensure_flow_compiled function',
    },
    500
  );
}

const response = results[0].result as EnsureCompiledResponse;

Suggested change

	const [result] = await options.sql`
	SELECT pgflow.ensure_flow_compiled(
	${flowSlug},
	${JSON.stringify(shape)}::jsonb,
	${mode}
	) as result
	`;
	const response = result.result as EnsureCompiledResponse;
	const results = await options.sql`
	SELECT pgflow.ensure_flow_compiled(
	${flowSlug},
	${JSON.stringify(shape)}::jsonb,
	${mode}
	) as result
	`;
	if (!results || results.length === 0 || !results[0]?.result) {
	return jsonResponse(
	{
	error: 'Database Error',
	message: 'No result returned from ensure_flow_compiled function',
	},
	500
	);
	}
	const response = results[0].result as EnsureCompiledResponse;

Spotted by Graphite Agent



Is this helpful? React 👍 or 👎 to let us know.

[github-actions]

🔍 Preview Deployment: Website

✅ Deployment successful!

🔗 Preview URL: https://pr-467.pgflow.pages.dev

📝 Details:

• Branch: 11-30-feat_edge-worker_add_ensure-compiled_endpoint_to_controlplane
• Commit: c994ef3758fedc07e28325383adfe079979721e1
• View Logs

_Last updated: _