ADRs 0012-0015

Author: Aksem

docs/adr/0012-item-level-and-collection-level-action-granularity.md

@@ -0,0 +1,85 @@
+# ADR-0012: Actions that process multiple items distinguish item and collection granularity
+
+- **Status:** accepted
+- **Date:** 2026-03-29
+- **Deciders:** @Aksem
+- **Tags:** actions, architecture
+
+## Context
+
+Some FineCode actions process more than one item of the same kind in one request, such as files, tests, or artifacts. This ADR addresses those actions.
+
+That creates a tension between two handler needs:
+
+1. **Per-item handlers** — formatters, simple linters — process each item independently. They gain nothing from seeing the full item list and become simpler when they receive exactly one item.
+
+2. **Batch-aware handlers** — type checkers, cross-file analyzers — benefit from receiving all items at once for whole-program analysis, shared caches, or batch-optimized tool invocations.
+
+If every such action is modeled only as a collection-level contract, single-item usage and naturally per-item handlers become awkward. A caller with one item must still use a batch-shaped payload and result model, and a handler that only transforms one item must still adapt itself to a collection contract.
+
+If every such action is modeled only as an item-level contract, batch-aware handlers become harder to express. Tools that need the full item set for correctness, shared context, or efficiency would be forced through per-item invocation patterns that do not match their natural unit of work.
+
+The design needs to support both per-item and batch-aware handlers without forcing one model onto every action that processes multiple items.
+
+## Related ADRs Considered
+
+- [ADR-0008](0008-explicit-specialization-metadata-for-language-actions.md) — defines language-specific specialization metadata that applies to both item-level and collection-level actions. This ADR is orthogonal: it addresses payload cardinality, not language dispatch.
+- [ADR-0009](0009-explicit-partial-result-token-propagation.md) — defines how partial results flow across action boundaries. Collection-level actions use partial results to stream per-item results; item-level actions typically do not need partial results since they produce a single result.
+- [ADR-0010](0010-progress-reporting-for-actions.md) — defines progress reporting for actions. Collection-level actions own per-item progress; item-level actions do not report progress for their single item (the parent orchestrator owns the narrative).
+
+## Decision
+
+FineCode will support **two complementary action granularity levels** for actions that process multiple items:
+
+1. **Item action** — the payload carries a single item, the result describes that one item. Handlers receive and return exactly one unit of work.
+
+2. **Collection action** — the payload carries a list of items, and the result describes that batch, typically with entries keyed per item. Handlers receive the full list and may iterate over items, batch-optimize, or cross-reference items.
+
+Both levels are ordinary actions in the FineCode action model. The distinction is architectural rather than hierarchical: the difference is in payload cardinality and handler intent, not in a separate framework category.
+
+### Main handler action
+
+When both item and collection actions exist for the same kind of operation, one usually serves as the **main handler action**. That is the action where the main handler logic naturally lives. The other action mainly adapts to it.
+
+- **Item-primary**: the main handlers attach to the item action. Appropriate when each tool processes one item independently (e.g. formatting).
+
+- **Collection-primary**: the main handlers attach to the collection action. An item action may exist as a convenience entry point for single-item callers. Appropriate when tools benefit from seeing all items at once (e.g. linting with type checkers).
+
+### Coexistence of both levels
+
+Both granularities may exist for the same kind of operation. In most cases, one of the corresponding actions serves as the main handler action: either an item-primary design or a collection-primary design. A collection-primary design may offer an item action as a convenience entry point for single-item callers, but it is not required.
+
+The architectural rule is that item and collection granularity remain distinct contracts. How a non-primary level adapts to the primary level is a design-guide concern rather than part of this decision record.
+
+### Language subactions at both levels
+
+Language-specific specialization ([ADR-0008](0008-explicit-specialization-metadata-for-language-actions.md)) applies independently at each level. An item-primary design may have:
+
+- `format_file` / `format_python_file` (item-level, language-specific — handlers register here)
+- `format_files` / `format_python_files` (collection-level, language-specific — orchestrates via delegation)
+
+A collection-primary design may have:
+
+- `lint_files` / `lint_python_files` (collection-level, language-specific — handlers register here)
+- `lint_file` / `lint_python_file` (item-level, language-specific — delegates, optional)
+
+## Consequences
+
+- **Cleaner single-item contract.** Callers and handlers can work with a contract shaped around one item rather than adapting a batch-oriented payload and result model.
+- **Batch optimization remains available.** Handlers that benefit from the full item list can still be exposed through collection-level actions or specialized subactions without forcing every invocation through a batch-oriented contract.
+- **More actions to define.** Each granularity level is a separate action with its own payload, context, and result types. This is additional surface area, but each type is simpler and more focused.
+- **Action designers must choose where the main handler logic lives.** The designing-actions guide documents criteria for this choice. Choosing incorrectly leads to awkward delegation patterns but is correctable without breaking handler contracts.
+
+### Alternatives Considered
+
+**Single collection-level action with framework-provided single-item adapter.** The framework would automatically unwrap single-element lists and wrap single results. Rejected because it hides the semantic difference between "one item" and "a batch of one" — the caller's intent and the handler's contract are genuinely different, and conflating them makes the API harder to reason about.
+
+**Force all multi-item work to item-level, with framework-provided batching.** Rejected because batch-aware handlers (type checkers, cross-file analyzers) need the full item list for correctness or performance. Forcing per-item invocation would either degrade their results or require them to maintain external state across calls.
+
+**Single collection-level design as an implementation approach.** These operations could be modeled only as collection-level actions, with single-item work represented as a batch of one. Rejected as the architectural rule because it makes the public contract batch-shaped even when the natural unit of work is one item, and because it pushes per-item handlers through an interface that does not match their semantics.
+
+### Related Decisions
+
+- Builds on [ADR-0008](0008-explicit-specialization-metadata-for-language-actions.md) (language subactions apply at both levels)
+- Builds on [ADR-0009](0009-explicit-partial-result-token-propagation.md) (collection actions use partial results for per-item streaming)
+- Builds on [ADR-0010](0010-progress-reporting-for-actions.md) (collection actions own per-item progress)

docs/adr/0013-action-declares-handler-execution-strategy.md

@@ -0,0 +1,144 @@
+# ADR-0013: Action declares handler execution strategy
+
+- **Status:** accepted
+- **Date:** 2026-03-29
+- **Deciders:** @Aksem
+- **Tags:** actions, architecture
+
+## Context
+
+When an action has multiple handlers, FineCode needs an explicit rule for how
+those handlers relate to one another.
+
+Some actions are **ordered pipelines**: each handler transforms the result of
+the previous one, so handler order is part of the action's semantics. Other
+actions are **independent fan-out**: handlers produce separate results, so the
+action does not depend on a particular order.
+
+If this relationship is not declared explicitly, the framework must infer it
+from naming conventions or other implementation-specific heuristics. That makes
+the action contract harder to review, easier to misapply, and less durable as
+the implementation evolves.
+
+The design also needs to stay clear about scope:
+
+- This ADR concerns the relationship **between handlers within one action**.
+- It does not decide whether a collection action processes different items
+  sequentially or in parallel.
+- It must apply consistently whether the action processes one unit of work
+  directly or schedules work that is later associated back to individual items.
+
+The architectural question is therefore not "how should the current runtime
+implement concurrency," but "where does the action's handler relationship
+belong as part of the contract?"
+
+### Where to declare the strategy
+
+Three levels were considered:
+
+- **Per-handler**: each handler declares its own execution preference. Rejected
+  because the relationship is between handlers, not inside one handler.
+  Individual handlers do not have enough context to define the contract for the
+  whole action, and conflicting declarations would be ambiguous.
+- **Per-action**: the action definition declares the strategy for how its
+  handlers relate. This places the decision with the action designer, who owns
+  the action's semantics.
+- **Per-invocation**: the caller or dispatcher chooses the strategy at runtime.
+  Rejected because the handler relationship is part of what the action means,
+  not a caller-specific tuning option.
+
+## Related ADRs Considered
+
+- [ADR-0012](0012-item-level-and-collection-level-action-granularity.md) — defines item-level and collection-level action granularity. The handler execution strategy applies at both levels: item actions with sequential handlers (format), collection actions with concurrent handlers (lint). The two ADRs are complementary.
+- [ADR-0009](0009-explicit-partial-result-token-propagation.md) — defines partial result flow across action boundaries. This ADR complements it by defining how one action's handlers relate when that action emits work incrementally.
+
+## Decision
+
+The **action definition** declares one handler execution strategy for the
+action. The framework applies that strategy uniformly wherever that action's
+handlers are composed.
+
+- **Sequential** (default): handlers run in definition order. Each handler's output can feed the next handler's input. Appropriate for transform pipelines (formatting: isort → ruff → save).
+
+- **Concurrent**: handlers run in parallel. Handlers produce independent results. Appropriate for independent analyzers (linting: ruff + mypy).
+
+### The action designer owns this decision
+
+The execution strategy describes how handlers within the action interact — whether they form a sequential pipeline (each transforms the previous output) or run independently (each produces separate results). This is a property of the action's semantics:
+
+- A formatting action is a sequential pipeline by design: handler order is part of the semantics.
+- A linting action runs independent analyzers by design: handler order is irrelevant.
+
+Individual handlers cannot correctly determine this. A handler only knows about itself — it cannot know whether other handlers in the chain depend on its output or run independently. Placing this decision on handlers would allow contradictory declarations and shift responsibility to the wrong party.
+
+### No mixed execution within a single action
+
+If one action would need some handlers to form a sequential pipeline and others
+to behave as independent concurrent peers during the same processing step, that
+is a sign that the action is combining distinct concerns. The correct response
+is to split it into multiple focused actions, each with a clear handler
+relationship, and compose them through orchestration.
+
+This rule is about **handler processing semantics**, not about every lifecycle
+phase that may exist around handler execution. Framework-managed setup,
+teardown, or other lifecycle behavior may still evolve independently so long as
+the action exposes one coherent handler relationship during processing.
+
+This is consistent with [ADR-0012](0012-item-level-and-collection-level-action-granularity.md) and the design principle "prefer multiple focused actions over one overloaded action."
+
+### Item-level parallelism is a separate concern
+
+Whether a collection action processes different items sequentially or in
+parallel is not governed by this decision. That is an orchestration concern. An
+action may therefore have sequential handler semantics per item while still
+being orchestrated across multiple items in parallel.
+
+## Consequences
+
+- **Action semantics become explicit.** Reviewers can see whether an action is
+  an ordered pipeline or a set of independent handlers without relying on
+  implementation-specific behavior.
+- **Handler responsibilities stay narrow.** Individual handlers do not need to
+  negotiate concurrency policy with one another.
+- **The same contract applies across action shapes.** The action's handler
+  relationship does not change just because the action is used for one item or
+  for a collection.
+- **Mixed processing semantics require composition.** Designs that genuinely
+  need both pipeline and fan-out semantics must express that through multiple
+  actions or explicit orchestration boundaries.
+- **The model can be extended later if needed.** If future action designs show a
+  recurring architectural need for more than one handler-processing dimension, a
+  later ADR can refine this rule without changing the meaning of the current
+  one.
+
+### Alternatives Considered
+
+**Handler-level declaration.** Each handler declares whether it should run
+sequentially or concurrently. Rejected because handler execution strategy is a
+relationship across the action, not a local property of one handler.
+
+**Configuration-level override.** The execution strategy is supplied from
+project configuration rather than from the action definition. Rejected as the
+primary mechanism because handler execution strategy is intrinsic to the action
+contract and should travel with the action definition.
+
+**Separate strategies for direct handler composition and per-item handler
+composition.** Deferred because current use cases treat these as the same
+architectural relationship. Revisit this if FineCode gains stable action
+semantics where handlers must be sequential in one processing context and
+concurrent in another, and that difference cannot be expressed cleanly as a
+lifecycle concern rather than a processing contract.
+
+### Related Decisions
+
+- Complements [ADR-0012](0012-item-level-and-collection-level-action-granularity.md) (item/collection granularity)
+- Clarifies the handler-composition side of incremental per-item work described alongside [ADR-0009](0009-explicit-partial-result-token-propagation.md)
+
+## Implementation Notes
+
+- In the current implementation, the same declared strategy should be applied
+  both when handlers run directly and when handler-produced work is later
+  grouped per item through `partial_result_scheduler`.
+- Runtime mechanisms such as task groups, scheduler internals, or future
+  lifecycle hooks are implementation choices rather than the architectural
+  decision itself.