ADR-0016: layered execution scopes. Initial implementation (partial)

Author: Aksem

docs/adr/0016-layered-execution-scopes-for-action-invocation.md

@@ -0,0 +1,110 @@
+# ADR-0016: Layered execution scopes for action invocation
+
+- **Status:** accepted
+- **Date:** 2026-04-05
+- **Deciders:** @Aksem
+- **Tags:** actions, architecture, orchestration, extension-runner, wm-server
+
+## Context
+
+Action invocation in FineCode occurs across architectural components and
+multiple execution scopes. In particular, FineCode distinguishes the Workspace
+Manager (WM) from Extension Runners (ERs), and invocation can cross those
+boundaries:
+
+- one action may invoke another within a single ER runtime boundary
+- one project-scoped request may require coordination across multiple execution
+  environments and runners
+- one workspace-scoped request may fan out across multiple projects under WM
+  coordination
+
+These scopes have different topology visibility, ownership boundaries, and
+operational controls.
+
+If one contract tries to cover all of them, local invocation semantics become
+coupled to orchestration concerns that they do not own. That makes the system
+harder to evolve and reason about because:
+
+- local nested action invocation and cross-boundary orchestration have
+  different guarantees
+- recursion and fan-out control apply to orchestration scopes, not local scope
+- WM-managed project/workspace topology should not leak into local ER
+  execution contracts
+
+FineCode needs an explicit architectural rule that distinguishes execution
+scopes while preserving generic, action-agnostic orchestration.
+
+## Related ADRs Considered
+
+- Reviewed [ADR-0003](0003-process-isolation-per-extension-environment.md) -
+  defines environment process isolation; this ADR defines invocation scope
+  boundaries across those processes.
+- Reviewed [ADR-0011](0011-wm-aggregates-progress-across-multi-project-action-runs.md) -
+  defines WM ownership for aggregated progress in fan-out requests; this ADR
+  defines execution interface layering for such fan-out.
+- Reviewed [ADR-0013](0013-action-declares-handler-execution-strategy.md) -
+  defines intra-action handler relationship; this ADR defines cross-boundary
+  invocation scope and ownership.
+
+## Decision
+
+FineCode adopts a layered execution model by scope:
+
+- Local execution scope: invocation within a single ER runtime boundary.
+- Project execution scope: invocation for one project under a project-scoped
+  contract.
+- Workspace execution scope: invocation across multiple projects under a
+  workspace-scoped contract.
+
+### Architectural boundaries
+
+1. Local execution contracts remain local and do not carry project/workspace
+   topology concerns.
+2. Cross-boundary orchestration is represented by separate higher-scope
+   contracts, not by widening local contracts.
+3. Project and workspace orchestration remain generic and action-agnostic, and
+   are owned by WM-level execution capabilities rather than ER-local contracts.
+4. Coordination that depends on shared resources across projects must model
+   those resources explicitly rather than relying on implicit shared state.
+
+### Ownership rule
+
+- ER-local components own local action invocation semantics.
+- WM-level orchestration owns cross-runner and cross-project coordination
+  mechanics.
+- Action-specific orchestration policy belongs to the orchestrating
+  action/service, not to generic orchestration infrastructure.
+
+## Consequences
+
+- One scope, one contract. Callers can choose local, project, or workspace
+  execution contracts explicitly.
+- Future-safe evolution. Single-project execution can evolve from local to
+  orchestrated without redefining local contracts.
+- No action-specific WM coupling. WM remains a generic execution mechanism for
+  project/workspace fan-out.
+- Additional interface surface. Introducing layered contracts increases
+  architectural surface area and requires clear naming/documentation.
+- Operational safeguards required. Orchestration scopes require recursion and
+  fan-out controls.
+
+### Alternatives Considered
+
+Directly using one unified action-runner interface across all scopes. Rejected
+because it conflates local and orchestration concerns, reducing contract clarity
+and increasing accidental coupling.
+
+Extending only the local runner interface to cover project/workspace
+orchestration. Rejected because topology-aware behavior is not a local concern
+and would blur ownership boundaries.
+
+Keeping orchestration implicit behind internal mechanisms without
+scope-specific contracts. Rejected because orchestration would remain implicit
+and difficult to reuse consistently from callers that need it.
+
+### Related Decisions
+
+- Complements [ADR-0003](0003-process-isolation-per-extension-environment.md)
+  by clarifying invocation semantics across isolated runner processes.
+- Refines [ADR-0011](0011-wm-aggregates-progress-across-multi-project-action-runs.md)
+  by defining broader execution-scope layering.

docs/adr/README.md

@@ -66,3 +66,4 @@ keep the same decision, would the ADR still read correctly?
 | 0013 | [Action declares handler execution strategy](0013-action-declares-handler-execution-strategy.md)                              | accepted | 2026-03-29 | actions, architecture                      |
 | 0014 | [CLI streams partial results in completion order](0014-cli-streams-partial-results-in-completion-order.md)                    | accepted | 2026-03-31 | cli, partial-results, ux                  |
 | 0015 | [Dedicated per-process WAL streams for durable execution lifecycle events](0015-dedicated-per-process-wal-streams-for-durable-lifecycle-events.md) | accepted | 2026-04-01 | architecture, reliability, recovery, logging, wal |
+| 0016 | [Layered execution scopes for action invocation](0016-layered-execution-scopes-for-action-invocation.md)                     | accepted | 2026-04-05 | actions, architecture, orchestration, extension-runner, wm-server |

finecode_extension_api/src/finecode_extension_api/code_action.py

@@ -56,6 +56,7 @@ class RunActionMeta:
     trigger: RunActionTrigger
     dev_env: DevEnv
     wal_run_id: str = ""
+    orchestration_depth: int = 0  # incremented at each cross-boundary hop
 
 
 class RunReturnCode(enum.IntEnum):

finecode_extension_api/src/finecode_extension_api/interfaces/iprojectactionrunner.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import collections.abc
+import pathlib
+import typing
+
+from finecode_extension_api import code_action, service
+from finecode_extension_api.interfaces.iactionrunner import ActionDeclaration
+
+PayloadT = typing.TypeVar("PayloadT", bound=code_action.RunActionPayload)
+ResultT = typing.TypeVar("ResultT", bound=code_action.RunActionResult)
+ActionT = typing.TypeVar(
+    "ActionT",
+    bound=code_action.Action[typing.Any, typing.Any, typing.Any],
+    covariant=True,
+)
+
+
+class IProjectActionRunner(service.Service, typing.Protocol):
+    """Run an action at project scope — across all env-runners of one project.
+
+    API mirrors IActionRunner: actions are identified by ActionDeclaration
+    (which carries the import-path source string). No caller_kwargs — caller
+    context does not cross process boundaries.
+
+    The implementation serializes payload to a dict, calls the WM back-channel
+    with the action's source path, and deserializes the response using the
+    action class's RESULT_TYPE. This is transparent to the handler author.
+    """
+
+    async def run_action(
+        self,
+        action: ActionDeclaration[code_action.Action[PayloadT, typing.Any, ResultT]],
+        payload: PayloadT,
+        meta: code_action.RunActionMeta,
+    ) -> ResultT: ...
+
+    def run_action_iter(
+        self,
+        action: ActionDeclaration[code_action.Action[PayloadT, typing.Any, ResultT]],
+        payload: PayloadT,
+        meta: code_action.RunActionMeta,
+    ) -> collections.abc.AsyncIterator[ResultT]: ...

finecode_extension_api/src/finecode_extension_api/interfaces/iworkspaceactionrunner.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import pathlib
+import typing
+
+from finecode_extension_api import code_action, service
+from finecode_extension_api.interfaces.iactionrunner import ActionDeclaration
+
+PayloadT = typing.TypeVar("PayloadT", bound=code_action.RunActionPayload)
+ResultT = typing.TypeVar("ResultT", bound=code_action.RunActionResult)
+ActionT = typing.TypeVar(
+    "ActionT",
+    bound=code_action.Action[typing.Any, typing.Any, typing.Any],
+    covariant=True,
+)
+
+
+class IWorkspaceActionRunner(service.Service, typing.Protocol):
+    """Fan-out an action across all workspace projects that declare it.
+
+    project_paths=None means all projects in the workspace that declare
+    the action.
+    """
+
+    async def run_action_in_projects(
+        self,
+        action: ActionDeclaration[code_action.Action[PayloadT, typing.Any, ResultT]],
+        payload: PayloadT,
+        meta: code_action.RunActionMeta,
+        project_paths: list[pathlib.Path] | None = None,
+    ) -> dict[pathlib.Path, ResultT]: ...

finecode_extension_runner/src/finecode_extension_runner/_services/run_action.py

@@ -273,6 +273,7 @@ async def run_action(
                         trigger=meta.trigger,
                         dev_env=meta.dev_env,
                         tracking_sender=tracking_sender,
+                        partial_result_queue=partial_result_queue,
                     )
 
                 if not isinstance(
@@ -385,6 +386,7 @@ async def run_action(
                                         trigger=meta.trigger,
                                         dev_env=meta.dev_env,
                                         tracking_sender=tracking_sender,
+                                        partial_result_queue=partial_result_queue,
                                     )
                                 )
                                 handlers_tasks.append(handler_task)
@@ -421,6 +423,7 @@ async def run_action(
                                 trigger=meta.trigger,
                                 dev_env=meta.dev_env,
                                 tracking_sender=tracking_sender,
+                                partial_result_queue=partial_result_queue,
                             )
                         except ActionFailedException as exception:
                             raise exception
@@ -793,6 +796,7 @@ async def execute_action_handler(
     trigger: str = "unknown",
     dev_env: str = "unknown",
     tracking_sender: _TrackingPartialResultSender | None = None,
+    partial_result_queue: asyncio.Queue | None = None,
 ) -> code_action.RunActionResult | None:
     logger.trace(f"R{run_id} | Run {handler.name} on {str(payload)[:100]}...")
     if wal_run_id is not None:
@@ -861,6 +865,11 @@ def get_run_context(param_type):
             stream_result: code_action.RunActionResult | None = None
             async for partial_result in call_result:
                 partial_result = typing.cast(code_action.RunActionResult, partial_result)
+                # Both paths below forward the partial to a caller — they differ only
+                # in transport.  partial_result_token sends to an LSP/MCP client via
+                # the WM notification channel; partial_result_queue delivers to a parent
+                # action handler that called run_action_iter().  These could be unified
+                # into a single PartialResultForwarder abstraction in the future.
                 if partial_result_token is not None:
                     if (
                         tracking_sender is not None
@@ -881,6 +890,8 @@ def get_run_context(param_type):
                     await partial_result_sender.schedule_sending(
                         partial_result_token, partial_result
                     )
+                if partial_result_queue is not None:
+                    await partial_result_queue.put(partial_result)
                 if stream_result is None:
                     result_type_pydantic = pydantic_dataclass(type(partial_result))
                     stream_result = typing.cast(
@@ -892,6 +903,8 @@ def get_run_context(param_type):
             if partial_result_token is not None:
                 await partial_result_sender.send_all_immediately()
                 execution_result = None  # partials already sent
+            elif partial_result_queue is not None:
+                execution_result = None  # each partial already forwarded to queue
             else:
                 execution_result = stream_result
         elif inspect.isawaitable(call_result):

finecode_extension_runner/src/finecode_extension_runner/di/bootstrap.py

@@ -18,7 +18,9 @@
     ifilemanager,
     ilogger,
     iprojectinfoprovider,
+    iprojectactionrunner,
     irepositorycredentialsprovider,
+    iworkspaceactionrunner,
 )
 
 from finecode_extension_runner import domain
@@ -33,9 +35,11 @@
     file_manager,
     inmemory_cache,
     loguru_logger,
+    project_action_runner,
     project_info_provider,
     repository_credentials_provider,
     service_registry,
+    workspace_action_runner,
 )
 
 def bootstrap(
@@ -49,6 +53,7 @@ def bootstrap(
     current_env_name_getter: Callable[[], str],
     handler_packages: set[str],
     service_declarations: list,
+    send_request_to_wm: Callable[[str, dict], collections.abc.Awaitable[Any]] | None = None,
 ):
     # logger_instance = loguru_logger.LoguruLogger()
     logger_instance = loguru_logger.get_logger()
@@ -75,6 +80,14 @@ def bootstrap(
     _state.container[icache.ICache] = cache_instance
     _state.container[iactionrunner.IActionRunner] = action_runner_instance
 
+    if send_request_to_wm is not None:
+        _state.container[iprojectactionrunner.IProjectActionRunner] = (
+            project_action_runner.ProjectActionRunnerImpl(send_request_to_wm)
+        )
+        _state.container[iworkspaceactionrunner.IWorkspaceActionRunner] = (
+            workspace_action_runner.WorkspaceActionRunnerImpl(send_request_to_wm)
+        )
+
     _state.container[irepositorycredentialsprovider.IRepositoryCredentialsProvider] = (
         repository_credentials_provider.ConfigRepositoryCredentialsProvider()
     )

finecode_extension_runner/src/finecode_extension_runner/impls/project_action_runner.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import collections.abc
+import dataclasses
+import typing
+from typing import Any, Awaitable, Callable
+
+from finecode_extension_api import code_action
+from finecode_extension_api.interfaces import iactionrunner, iprojectactionrunner
+from finecode_extension_runner import run_utils
+
+PayloadT = typing.TypeVar("PayloadT", bound=code_action.RunActionPayload)
+ResultT = typing.TypeVar("ResultT", bound=code_action.RunActionResult)
+
+
+class ProjectActionRunnerImpl(iprojectactionrunner.IProjectActionRunner):
+    """Calls the WM back-channel finecode/runActionInProject."""
+
+    def __init__(self, send_request_to_wm: Callable[[str, dict], Awaitable[Any]]) -> None:
+        self._send = send_request_to_wm
+
+    async def run_action(
+        self,
+        action: iactionrunner.ActionDeclaration[code_action.Action[PayloadT, typing.Any, ResultT]],
+        payload: PayloadT,
+        meta: code_action.RunActionMeta,
+    ) -> ResultT:
+        action_source: str = action.source  # type: ignore[attr-defined]
+        action_cls = run_utils.import_module_member_by_source_str(action_source)
+        raw_result = await self._send(
+            "finecode/runActionInProject",
+            {
+                "actionSource": action_source,
+                "payload": dataclasses.asdict(payload),
+                "meta": {
+                    "trigger": meta.trigger.value,
+                    "devEnv": meta.dev_env.value,
+                    "orchestrationDepth": meta.orchestration_depth,
+                },
+            },
+        )
+        result_dict = raw_result.get("result", {}) or {}
+        return action_cls.RESULT_TYPE(**result_dict)
+
+    def run_action_iter(
+        self,
+        action: iactionrunner.ActionDeclaration[code_action.Action[PayloadT, typing.Any, ResultT]],
+        payload: PayloadT,
+        meta: code_action.RunActionMeta,
+    ) -> collections.abc.AsyncIterator[ResultT]:
+        raise NotImplementedError(
+            "run_action_iter is not supported for project-scope execution"
+        )