Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

Architecture Decision Records

Dated, immutable records of the structural decisions that shaped Orkeon. A superseded ADR keeps its original text as an archive; the superseding one links back.

Why does the numbering start at 002? There is no ADR-001 β€” the first decision recorded as an ADR was numbered 002 and the gap was kept rather than renumbering, so existing cross-references stay stable.

ADR Decision Status
ADR-002 Orkeon.Tools.Abstractions as a shared kernel (the Infrastructure β†’ Tools.Abstractions exception) Accepted
ADR-003 Secondary shared kernels: Application β†’ Analysis.Abstractions, Infrastructure β†’ Analysis Accepted
ADR-004 The scripting naming twins, documented without renaming Superseded by ADR-007
ADR-005 The heterogeneous Tools.* family (Tools.Web/Tools.EventHub β†’ Application) Accepted
ADR-006 The src/rag/ subsystem: Orkeon.Rag.Abstractions shared kernel, legacy RAG namespaces removed without shims Accepted
ADR-007 Decision D3: Orkeon.Cli.Scripting renamed to Orkeon.Cli.Commands.Scripting before any NuGet publish Accepted
ADR-008 A physical path is never a virtual path: runners mount under a name, infrastructure mounts are invisible to agents Accepted β€” its RunnerMounts is now RunnerVirtualRoots (ADR-009); the decision stands, the type moved
ADR-009 A constant two projects must agree on lives in a zero-dependency satellite, not in a hand-written copy guarded by a drift test Accepted β€” implemented (five satellites under src/constants/)
ADR-010 Microsoft Agent Framework interop is a separate package (Orkeon.Interop.AgentFramework), in both directions: a crew as an AIAgent, an AIAgent as brain or tool of an Orkeon agent; the initial context finally reaches the prompts Accepted
ADR-011 The runners export OpenTelemetry by the standard contract (OTEL_EXPORTER_OTLP_ENDPOINT); Orkeon.Hosting.Aspire adds them to an AppHost; the Aspire dashboard is the cross-platform observability surface and no web front-end will be built Accepted
ADR-012 The e-mail tool family (Orkeon.Tools.Email) is the second motivated exception to the scope freeze: MailKit/MimeKit for IMAP, POP3 and SMTP, Microsoft Graph for Outlook.com, hand-written OAuth2 with tokens in the internal /credentials root behind the privileged VFS view, per-account rights and a fail-closed send allow-list; email_parser rebuilt into it Accepted
ADR-013 The drive tool family (Orkeon.Tools.Drive) is the third motivated exception to the scope freeze: Google Drive and OneDrive in plain HTTP, the OAuth layer moved to Orkeon.Tools.Abstractions and shared with e-mail, per-account rights and root folder, a fail-closed share allow-list, tokens in the drive subdirectory of /credentials Accepted
ADR-014 shell_command is confined by the operating system by default: Auto picks bubblewrap, Seatbelt or an AppContainer, none inside a container, the call fails closed when the backend cannot run; one persistent shell session per agent run, killed with the run Accepted
ADR-015 Model providers come in four categories (generation, embedding, reranking, decision), each with its own contract and listed in ModelProviderCatalog; the System One decision providers (TypeSafe, Liquid, Kev) sit behind a separate IDecisionModel port, not as a 17th LLM provider; a decision stage around an LLM call blocks, routes or escalates and never rewrites Accepted
ADR-016 A decision task asks the decision model typed questions without an agent, and a when condition on a later task reads its answers to run or skip it; Sequential, Parallel and Graph support them and the other processes refuse them on load; a false condition skips and never fails; the richer model (decision nodes around a task, loops, a journal) is deferred Accepted
ADR-017 The transcript paints runs over a text that stays the one source for wrap and selection; only content paints a background, and scripts hand over a source and a kind, never a colour Accepted
ADR-018 Two graph engines stay (Domain and JavaScript) and share one topology validation, one vocabulary and the Domain's budgets; a YAML graph: block (nodes, edges with when, start, maxTransitions, maxVisits) replaces graphConfig:, several edges from a decision task become one conditional edge with a mandatory "otherwise", and a crew without the block runs one node per task Accepted
ADR β€” RaggableTree 5-level-plus-edges stratified semantic graph via Tree-sitter (unnumbered β€” lives with its architecture guide; amended 2026-08-18) Accepted