See also: ADR-003 — Secondary shared kernels · Back to the index
ADR-005 — Heterogeneous Tools.* family: Tools.Web and Tools.EventHub depend on Application
Status: Accepted · Date: 2026-06 · Scope: Orkeon.Tools.Web → Orkeon.Application; Orkeon.Tools.EventHub → Orkeon.Application
Context
The Tools.* family of tool packages is not homogeneous in its dependencies:
- Four packages (
Tools.Code,Tools.Data,Tools.FileSystem,Tools.Analysis) make do withOrkeon.Tools.Abstractions(+ abstractions), in line with the expected profile: a tool should depend only on the tool contracts and onDomain. - Two packages (
Tools.WebandTools.EventHub) reach up toOrkeon.Application.
This asymmetry may surprise a contributor who expects all Tools.* packages to share the same
dependency baseline.
Decision
Accept and document that Tools.Web and Tools.EventHub depend on Application, because their
tools need application services (ports/use cases) that Tools.Abstractions alone does not expose —
for example task coordination, A2A channels, or application context services.
The dependency direction remains correct: Tools.Web/Tools.EventHub are peripheral packages that
depend on Application (an inner layer), and not the other way around. No cycle, no inversion.
Rejected alternatives
- Force every
Tools.*package to depend only onTools.Abstractions. Rejected: this would require duplicating application contracts, or hoisting intoTools.Abstractionscontracts that have no place in a package of pure tool abstractions, or introducing artificial indirections. - Move
Tools.Web/Tools.EventHubout of theTools.*family. Rejected: they are genuinely tool providers; their place in theTools.*nomenclature is consistent for discovery and packaging.
Consequences
- Positive: the implicit rule "a
Tools.*package may depend onApplicationwhen its tools require application services" is now explicit. Reviews no longer have to settle this case on a one-off basis. - Vigilance: prefer depending on
Tools.Abstractionsalone as long as a tool has no proven application-level need; only reach up toApplicationout of documented necessity.
Amendment (2026-08-23)
The Context's package split has drifted — exactly the drift the Vigilance clause
exists to record. Current state: only Tools.Code still matches the
"abstractions-only" profile among the four originally listed. Tools.Data,
Tools.FileSystem and Tools.Rag now reference the concrete Orkeon.Rag (for the
RAG-backed search tools), which itself references Orkeon.Application (ADR-006
amendment of 2026-07-25) — so they reach Application transitively; Tools.Analysis
references the concrete Orkeon.Analysis. The decision itself is unchanged: reaching
up is legitimate when documented, and ADR-006 documents the RAG couplings.
Since then (2026-09-26): Tools.Web references the concrete Orkeon.Rag as well as
Application; Tools.Email (ADR-012) reaches
Application the same transitive way, through Orkeon.Rag and its prompt-injection
detector; Tools.Embeddings.Local matches the "abstractions-only" profile
(Domain, Tools.Abstractions, Analysis.Abstractions).
Amendment (2026-10-29)
Tools.Drive (ADR-013) references Domain, Tools.Abstractions, Orkeon.Constants.Configuration and the concrete Orkeon.Rag, so it reaches Application transitively through Orkeon.Rag, like Tools.Web and Tools.Email.
Amendment (2026-11-06)
Tools.Web references the concrete Orkeon.Analysis as well: the firefox tool reads a page as a semantic graph, in an InMemoryRaggableStore of its own per page (never the code index of the host), and the projection of a page outline lives in Orkeon.Analysis (PageOutlineMapper), beside the other mappers, because the mutators of a graph node are internal to it. Orkeon.Analysis is already part of the Orkeon package: the closure of the packages is unchanged.