π«π· 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 |