feat(sync-service): remove subquery feature flags (#4741)

## Summary

Subqueries in shape WHERE clauses are now permanently enabled and
treated as a generally-available feature. This removes the two gating
flags — `allow_subqueries` and `tagged_subqueries` — so there is no way
to turn subqueries off, and cleans up the code that only existed to
support their disabled paths.

## Changes

- **config**: empty `@known_feature_flags` and simplify the
`feature_flags` default. The generic `ELECTRIC_FEATURE_FLAGS` mechanism
(env var, parsing, plumbing) is intentionally **retained** for future
flags — it just has no flags defined now.
- **`allow_subqueries` removal**:
- `shape.ex`: drop `check_feature_flag/2` — subqueries are always
allowed.
- `consumer/state.ex`: drop the `"allow_subqueries" in feature_flags`
disjunct. Non-subquery shapes keep fragment streaming, matching current
production behavior; only shapes with dependencies / inner subquery
shapes use full-txn buffering.
- **`tagged_subqueries` removal** — the dependency move policy collapses
to always stream:
  - `event_handler_builder.ex`: remove `dependency_move_policy/2`.
- `subqueries/shape_info.ex`: remove the `dependency_move_policy` field
and type.
- `event_handler/subqueries/steady.ex`: remove the
`:invalidate_on_dependency_move` clause that returned `{:error,
:unsupported_subquery}`.
- `consumer.ex`: remove the now-unreachable `:unsupported_subquery`
error handler.
- **tests**: remove all `@tag allow_subqueries: false` tags + the setup
conditional, strip `feature_flags: ["allow_subqueries"]` args, and
delete the two obsolete invalidate-policy tests.
- **docs**: reframe subqueries as GA — remove the "Preview feature"
callout and flag wording in `shapes.md` (section/anchor renamed to
`#subqueries`), collapse the `config.md` Feature Flags section to a
minimal `ELECTRIC_FEATURE_FLAGS` entry, move subqueries out of
"Unsupported" in the client skill, and drop the `ELECTRIC_FEATURE_FLAGS`
line from the agents-server dev compose.

## Notes

With the test-env `feature_flags` default now empty and the
`allow_subqueries` disjunct gone, simple non-subquery shapes exercise
fragment streaming by default in tests (matching production) rather than
txn-buffering. The full suite passes under that.

## Test Plan

- [x] `mix format --check-formatted` clean
- [x] `mix compile --warnings-as-errors` clean (confirms no dead clauses
/ unused vars)
- [x] Full suite: **2277 passed, 0 failures**, 25 excluded
- [x] Subquery shape requests succeed without any
`ELECTRIC_FEATURE_FLAGS` set (covered by `serve_shape_plug_test` /
`subqueries_test`)

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- codesmith:footer -->
---
<a
href="https://app.blacksmith.sh/electric-sql/codesmith/electric/pr/4741"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v2.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-light-v2.svg"><img
alt="View with [code]smith"
src="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v2.svg"></picture></a>
<a
href="https://backend.blacksmith.sh/track/enable-autofix?expires=1787816001&installation_model_id=8736&pr_number=4741&repository=electric-sql%2Felectric&return_to=https%3A%2F%2Fgithub.com%2Felectric-sql%2Felectric%2Fpull%2F4741&signature=fd5a7f3eddfda2bf413c9b925e4089a9c54cc35327a5441fe86d84188b5145a3"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-light.svg"><img
alt="Autofix with [code]smith"
src="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark.svg"></picture></a>
<sup>Need help on this PR? Tag <code>@codesmith-bot</code> with what you
need. Autofix is disabled.</sup>

<!-- codesmith:autofix:disabled -->
<!-- /codesmith:footer -->

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: robacourt

.changeset/subqueries-generally-available.md

@@ -0,0 +1,7 @@
+---
+"@core/sync-service": patch
+"@electric-sql/client": patch
+"@electric-ax/agents-server": patch
+---
+
+Subqueries in shape WHERE clauses are now generally available and always enabled, including incremental move handling for compound `AND`/`OR`/`NOT` expressions. The `allow_subqueries` and `tagged_subqueries` feature flags have been removed — they no longer need to be set via `ELECTRIC_FEATURE_FLAGS`.

packages/agents-server/docker-compose.dev.yml

@@ -30,7 +30,6 @@ services:
     environment:
       DATABASE_URL: postgresql://electric_agents:electric_agents@postgres:5432/electric_agents
       ELECTRIC_INSECURE: 'true'
-      ELECTRIC_FEATURE_FLAGS: allow_subqueries
     depends_on:
       postgres:
         condition: service_healthy

packages/sync-service/lib/electric/config.ex

@@ -38,7 +38,7 @@ defmodule Electric.Config do
 
   @build_env Mix.env()
 
-  @known_feature_flags ~w[allow_subqueries tagged_subqueries]
+  @known_feature_flags ~w[]
   @default_storage_dir "./persistent"
 
   @defaults [
@@ -133,7 +133,7 @@ defmodule Electric.Config do
     consumer_gc_heap_threshold: nil,
     ## Misc
     process_registry_partitions: &Electric.Config.Defaults.process_registry_partitions/0,
-    feature_flags: if(Mix.env() == :test, do: @known_feature_flags, else: []),
+    feature_flags: [],
     publication_refresh_period: 60_000,
     schema_reconciler_period: 60_000,
     snapshot_timeout_to_first_data: :timer.seconds(30),

packages/sync-service/lib/electric/shapes/consumer.ex

@@ -1026,10 +1026,6 @@ defmodule Electric.Shapes.Consumer do
     handle_txn_with_truncate(xid, state)
   end
 
-  defp handle_event_error(state, :unsupported_subquery) do
-    mark_for_removal(state)
-  end
-
   defp handle_event_error(state, :buffer_overflow) do
     Logger.warning("Subquery buffer overflow for #{state.shape_handle} - terminating shape")
 

packages/sync-service/lib/electric/shapes/consumer/event_handler/subqueries/steady.ex

@@ -36,15 +36,6 @@ defmodule Electric.Shapes.Consumer.EventHandler.Subqueries.Steady do
     {:ok, state, []}
   end
 
-  def handle_event(
-        %__MODULE__{
-          shape_info: %ShapeInfo{dependency_move_policy: :invalidate_on_dependency_move}
-        },
-        {:materializer_changes, _dep_handle, _payload}
-      ) do
-    {:error, :unsupported_subquery}
-  end
-
   def handle_event(%__MODULE__{} = state, {:materializer_changes, dep_handle, payload}) do
     subquery_ref = RefResolver.ref_from_dep_handle!(state.shape_info.ref_resolver, dep_handle)
     dep_index = subquery_ref |> List.last() |> String.to_integer()

packages/sync-service/lib/electric/shapes/consumer/event_handler_builder.ex

@@ -13,7 +13,6 @@ defmodule Electric.Shapes.Consumer.EventHandlerBuilder do
   def build(%State{shape: %Shape{shape_dependencies_handles: dep_handles}} = state, action)
       when dep_handles != [] do
     {:ok, dnf_plan} = DnfPlan.compile(state.shape)
-    dependency_move_policy = dependency_move_policy(state.stack_id, state.shape)
 
     {views, dep_handle_to_ref, dep_index_to_ref} =
       dep_handles
@@ -44,8 +43,7 @@ defmodule Electric.Shapes.Consumer.EventHandlerBuilder do
         dnf_plan: dnf_plan,
         ref_resolver:
           Electric.Shapes.Consumer.Subqueries.RefResolver.new(dep_handle_to_ref, dep_index_to_ref),
-        buffer_max_transactions: buffer_max_transactions,
-        dependency_move_policy: dependency_move_policy
+        buffer_max_transactions: buffer_max_transactions
       },
       views: views
     }
@@ -63,14 +61,4 @@ defmodule Electric.Shapes.Consumer.EventHandlerBuilder do
 
     {:ok, handler, [%SetupEffects.SubscribeShape{action: action}]}
   end
-
-  defp dependency_move_policy(stack_id, _shape) do
-    feature_flags = Electric.StackConfig.lookup(stack_id, :feature_flags, [])
-
-    if "tagged_subqueries" not in feature_flags do
-      :invalidate_on_dependency_move
-    else
-      :stream_dependency_moves
-    end
-  end
 end

packages/sync-service/lib/electric/shapes/consumer/state.ex

@@ -119,7 +119,6 @@ defmodule Electric.Shapes.Consumer.State do
 
   @spec initialize_shape(uninitialized_t(), Shape.t(), map()) :: uninitialized_t()
   def initialize_shape(%__MODULE__{} = state, shape, opts) do
-    feature_flags = Map.get(opts, :feature_flags, [])
     is_subquery_shape? = Map.get(opts, :is_subquery_shape?, false)
 
     %{
@@ -128,8 +127,7 @@ defmodule Electric.Shapes.Consumer.State do
         # Enable direct fragment-to-storage streaming for shapes without subquery dependencies
         # and if the current shape itself isn't an inner shape of a shape with subqueries.
         write_unit:
-          if "allow_subqueries" in feature_flags or shape.shape_dependencies != [] or
-               is_subquery_shape? do
+          if shape.shape_dependencies != [] or is_subquery_shape? do
             @write_unit_txn
           else
             @write_unit_txn_fragment

packages/sync-service/lib/electric/shapes/consumer/subqueries/shape_info.ex

@@ -5,25 +5,21 @@ defmodule Electric.Shapes.Consumer.Subqueries.ShapeInfo do
   alias Electric.Shapes.DnfPlan
   alias Electric.Shapes.Shape
 
-  @type dependency_move_policy :: :stream_dependency_moves | :invalidate_on_dependency_move
-
   @enforce_keys [
     :shape,
     :stack_id,
     :shape_handle,
     :dnf_plan,
     :ref_resolver,
-    :buffer_max_transactions,
-    :dependency_move_policy
+    :buffer_max_transactions
   ]
   defstruct [
     :shape,
     :stack_id,
     :shape_handle,
     :dnf_plan,
     :ref_resolver,
-    :buffer_max_transactions,
-    :dependency_move_policy
+    :buffer_max_transactions
   ]
 
   @type t() :: %__MODULE__{
@@ -32,7 +28,6 @@ defmodule Electric.Shapes.Consumer.Subqueries.ShapeInfo do
           shape_handle: String.t(),
           dnf_plan: DnfPlan.t(),
           ref_resolver: RefResolver.t(),
-          buffer_max_transactions: pos_integer(),
-          dependency_move_policy: dependency_move_policy()
+          buffer_max_transactions: pos_integer()
         }
 end

packages/sync-service/lib/electric/shapes/shape.ex

@@ -295,7 +295,6 @@ defmodule Electric.Shapes.Shape do
   defp validate_where_clause(where, %{inspector: inspector} = opts, refs) do
     with {:ok, where} <- Parser.parse_query(where),
          {:ok, subqueries} <- Parser.extract_subqueries(where),
-         :ok <- check_feature_flag(subqueries, opts),
          {:ok, shape_dependencies, sublink_dependency_indexes} <-
            build_shape_dependencies(subqueries, opts),
          {:ok, dependency_refs} <- build_dependency_refs(shape_dependencies, inspector),
@@ -318,15 +317,6 @@ defmodule Electric.Shapes.Shape do
     end
   end
 
-  defp check_feature_flag(subqueries, opts) do
-    if subqueries != [] and
-         not Enum.member?(opts.feature_flags, "allow_subqueries") do
-      {:error, {:where, "Subqueries are not supported"}}
-    else
-      :ok
-    end
-  end
-
   defp make_opts_from_select(select, opts) do
     with {:ok, {columns, from, where}} <- Parser.extract_parts_from_select(select) do
       {:ok,

packages/sync-service/test/electric/plug/serve_shape_plug_test.exs

@@ -267,7 +267,6 @@ defmodule Electric.Plug.ServeShapePlugTest do
       ctx =
         ctx
         |> Map.put(:inspector, @subquery_inspector)
-        |> Map.put(:feature_flags, ["allow_subqueries"])
 
       Repatch.patch(Electric.Shapes, :fetch_handle_by_shape, fn _, _ ->
         flunk("should reject before checking whether the shape already exists")