🇬🇧 English version
Conformité VFS
Orkeon impose au code du framework un principe Virtual File System (VFS) uniquement : tout accès au système de fichiers doit passer par IFileSystemService afin que les frontières de mounts, les droits d'accès et la validation des chemins soient respectés uniformément. L'usage direct de System.IO.File, System.IO.Directory, FileStream, FileInfo, DirectoryInfo et FileSystemWatcher est interdit dans les assemblies du framework.
Ce document décrit :
- l'analyseur Roslyn
Orkeon.Compliance.Vfsqui applique la règle à la compilation - ses sept codes de diagnostic
ORKVFSet leurs sévérités (le même analyseur porte aussiORKCON001, voir Conformité console) - les périmètres exemptés et la manière d'opter pour une exception documentée
L'analyseur
Projet : src/analyzers/Orkeon.Compliance.Vfs/
Cible : analyseur Roslyn netstandard2.0, câblé dans src/Directory.Build.props avec OutputItemType=Analyzer.
L'analyseur s'applique à chaque projet sous src/ sauf lui-même (une ProjectReference avec ReferenceOutputAssembly=false), donc les violations cassent le build immédiatement. tests/analyzers/Orkeon.Compliance.Vfs.Tests exerce chaque règle sur des extraits compilés.
Les appels sont jugés sur leur symbole résolu, pas sur leur graphie : using static System.IO.File; ReadAllText(p) déclenche ORKVFS001 comme File.ReadAllText(p), et un FileStream fs = new(path, …) typé par la cible déclenche ORKVFS003 comme new FileStream(path, …).
Le même analyseur est publié sur NuGet sous le nom Orkeon.Compliance.Vfs (dépendance de développement, sans aucune dépendance d'exécution vers Orkeon — voir la matrice de publication), pour les projets qui veulent le même garde-fou. Hors de ce dépôt, ses sévérités se règlent de la manière Roslyn standard, dans .editorconfig (dotnet_diagnostic.ORKVFS007.severity = none pour un projet qui n'utilise pas IFileSystemService).
Codes de diagnostic
Tous les diagnostics sont définis dans src/analyzers/Orkeon.Compliance.Vfs/DiagnosticDescriptors.cs et émettent un lien d'aide stable finissant en #ork-vfs-00N — les ancres de la colonne Code ci-dessus sont ces cibles.
Périmètres exemptés (par chemin)
L'analyseur ignore les chemins de l'allowlist (SystemIoUsageAnalyzer.IsExemptByPath). Elle est volontairement étroite — les exemptions par dossier entier ont été remplacées par une allowlist explicite par fichier, pour qu'un nouveau fichier sous le même dossier ne soit pas exempté silencieusement.
Exemptions par dossier (s_exemptFolderSegments) :
/core/Orkeon.Domain/FileSystem/— contrats publics du VFS (l'abstraction elle-même)/core/Orkeon.Infrastructure/FileSystem/— implémentation du VFS (disk/fake/watcher)/tests/— les fixtures reposent surDiskBackedFileSystemServiceet le disque réel/examples/— hors périmètre de conformité du framework
Exemptions par fichier (s_exemptFileSuffixes) — chacune porte un marqueur inline EXCEPTION-… / OUT-OF-SCOPE :
Sandbox/SandboxSession.cs— mounts enregistrés avant la DI (EXCEPTION-BOOTSTRAP)Sandbox/HostProcessRunner.cs,Sandbox/DockerSandbox.cs— sondage de binaires hôte (OUT-OF-SCOPE)Security/PathValidator.cs— la résolution symlink/realpath est son rôle
Tout autre fichier légitimement « brut » s'appuie sur un [SuppressVfsCompliance] étroit au site d'usage plutôt qu'une exemption par chemin (voir les exceptions permanentes ratifiées ci-dessous).
Opt-out : [SuppressVfsCompliance]
Pour les exceptions documentées qui ne correspondent à aucune exemption par chemin, appliquer l'attribut déclaré dans src/core/Orkeon.Domain/Attributes/SuppressVfsComplianceAttribute.cs (espace de noms Orkeon.Compliance.Vfs). L'analyseur le reconnaît à son nom complet, pas à son assembly : un projet qui ne référence pas Orkeon.Domain en déclare sa propre copie internal — c'est ce que fait Orkeon.Hosting.Aspire :
[Orkeon.Compliance.Vfs.SuppressVfsCompliance("EXCEPTION-BOOTSTRAP: provisions the physical directory the /sandbox mount points at")]
internal sealed partial class SandboxSession { … }
[SuppressVfsCompliance("OUT-OF-SCOPE: probes external toolchain (esbuild) binary location, not a VFS mount.")]
internal string ResolveBinary() { … }
Placement :
- Assembly — opt-out large pour un projet entier (à utiliser avec parcimonie, préférer un périmètre plus étroit).
- Classe / struct — exempte tous les membres d'un type (p. ex. une classe de bootstrap comme
RunnerHost). - Méthode / constructeur / propriété / champ — périmètre le plus étroit.
L'argument reason est obligatoire et doit nommer la catégorie d'audit dont il relève :
EXCEPTION-BOOTSTRAP— s'exécute avant l'enregistrement des mounts VFS.EXCEPTION-WATCHER-BRIDGE— adaptateur qui enveloppeSystem.IO.FileSystemWatcherpour implémenter un port watcher Orkeon.OUT-OF-SCOPE— sondage au niveau de l'hôte (chemin d'installation du SDK, découverte de binaires système) qui ne cible jamais un mount VFS.
EXCEPTION-BACKCOMPAT et EXCEPTION-OBSOLETE ne sont pas des catégories acceptées : tout outil ou
service prend un IFileSystemService non nullable (un nullable déclenche ORKVFS007).
Toute nouvelle classe d'exception doit d'abord être consignée dans l'audit de conformité VFS (l'archive des mainteneurs, audit-vfs-compliance-*) avant l'ajout d'une suppression.
Exceptions permanentes ratifiées
Ces accès ne peuvent pas passer par le VFS par nature et sont définitivement autorisés via les marqueurs [SuppressVfsCompliance] inline (ou l'allowlist par chemin) :
| Domaine | Emplacement | Catégorie | Justification |
|---|---|---|---|
| Implémentation VFS | Domain/FileSystem/*, Infrastructure/FileSystem/* |
(l'abstraction) | C'est le VFS |
| Bootstrap (pré-DI) | SandboxSession, ConsoleApp Cli*MountBootstrapper, Hosting/Runner*, Hosting/CrewMountDeclarations (pré-lit le bloc mounts: d'une crew) |
EXCEPTION-BOOTSTRAP |
Lisent appsettings + montent avant que le VFS existe. Couvre le provisionnement d'un montage, jamais l'exposition d'un chemin physique comme chemin virtuel — voir ADR-008 |
| Sondage hĂ´te | DockerSandbox, HostProcessRunner, ProcessGitDiffProvider |
OUT-OF-SCOPE |
Découvrent docker/dotnet/git sur le PATH, jamais un mount |
| Toolchain | Scripting/Toolchain/EsbuildTranspiler.cs |
OUT-OF-SCOPE |
Localise le binaire esbuild + fichiers temp de transpilation ; chaîne d'outils hôte |
| Toolchain (vérification de types) | Scripting/Toolchain/TscTypeChecker.cs |
OUT-OF-SCOPE (localiser tsc), EXCEPTION-BOOTSTRAP (le dossier de travail) |
tsc est un processus externe qui lit et imprime des chemins physiques : le vérificateur écrit un dossier de travail (roll-up des typings, tsconfig, copies du script et de ses modules importés dont le pragma orkeon-script est blanchi) sous le répertoire temporaire, hors du VFS et non monté : rien dans le framework ne le relit. Chaque chemin de la sortie du compilateur et d'un message d'échec est remappé vers son chemin virtuel avant affichage ; le dossier est supprimé à la fin, y compris sur annulation |
| Applications hôtes (pré-DI) | orkeon-host (CrewHostService, HostCrewMounts, HostStartup), Hosting/CrewDirectoryLayout, le point d'entrée orkeon (Orkeon.Scripting.Cli, à l'échelle de l'assembly), le Program du REPL |
EXCEPTION-BOOTSTRAP |
Valident ou classent les chemins de crew, de script et de settings fournis par l'opérateur avant qu'aucun mount n'existe |
| Primitive sécurité | Security/PathValidator.cs |
(allowlist) | résolution symlink/realpath = son rôle |
| Watcher bridge | Analysis/.../FileSystemWatcherCodebaseWatcher.cs |
EXCEPTION-WATCHER-BRIDGE |
Adapte System.IO.FileSystemWatcher vers ICodebaseWatcher |
| Sonde RaggableTree | Analysis/Core/FileSystemDiscoverer.cs (sonde diagnostique uniquement) |
OUT-OF-SCOPE |
La découverte batch elle-même utilise EnumerateFilesAsync ; la sonde compte délibérément les entrées physiques pour distinguer « le VFS n'a rien renvoyé » de « le disque est vide » |
| Persistance SQLite | SqliteMemoryProvider, SqliteStateStore |
gouverné | Le moteur exige un chemin réel ; le Data Source est résolu via ResolveAndValidate avant d'atteindre le driver |
Ajouter un nouvel outil ou service
- Déclarer un paramètre de constructeur
IFileSystemServicerequis, non-nullable et l'injecter via la DI (un nullable déclencheORKVFS007). Le valider avecArgumentNullException.ThrowIfNull. - Travailler en chemins virtuels (
/workspace/...,/output/...,/tmp/...). - Ne jamais ajouter de fallback
System.IOpar cheminstring. Il n'existe pas de constructeur de rétro-compatibilité — la DI est la seule voie de construction. - Pour énumérer, streamer, copier ou observer, utiliser les méthodes dédiées de
IFileSystemServiceplutôt que les primitivesSystem.IOéquivalentes (y comprisStreamReader/StreamWriter— envelopper unStreamissu deOpenReadStreamAsync/OpenWriteStreamAsync, jamais un chemin).
Mounts, droits et visibilité
IFileSystemService (Orkeon.Domain.FileSystem) est toute la surface dont un composant a
besoin : ResolveAndValidate (virtuel → physique, contrôlé contre un FileAccessRights
requis), ToVirtualPath, GetAvailableMounts, EnumerateFilesAsync, ExistsAsync,
GetEntryKindAsync, TryGetEntryAsync, TryReadAllTextAsync / TryReadAllBytesAsync,
OpenReadStreamAsync, WriteAllTextAsync / WriteAllBytesAsync / AppendAllTextAsync,
OpenWriteStreamAsync / OpenAppendStreamAsync, CreateDirectoryAsync, DeleteAsync,
CopyAsync. Les notifications de changement viennent de l'interface distincte
IVirtualFileSystemWatcher. AddOrkeonFileSystem(configuration) enregistre les deux.
Un mount se déclare par une chaîne — [<ulid>|]<physique>:<virtuel>:<droits>[;<sous-chemin>:<droits>…] :
<virtuel>doit commencer par/; un chemin physique qui contient:ou;, ou qui finit par une barre oblique inverse, se met entre guillemets ("C:\src\":/workspace:ro).<droits>vautro(FileAccessRights.ReadOnly),rw(ReadWrite= Read, Write, Create, Delete) ourwnd(ReadWriteNoDelete) ; chaque;<sous-chemin>:<droits>redéfinit les droits d'un sous-arbre.- L'ULID facultatif de 26 caractères avant
|identifie l'entrée — voir la référence de configuration.
FileAccessRights est une énumération de drapeaux (Read, Write, Create, Delete) ;
chaque opération déclare le droit qu'elle exige et le registre refuse l'appel quand le mount
(ou la redéfinition du sous-arbre) ne l'accorde pas. MountVisibility vaut AgentFacing (le
défaut, listé par GetAvailableMounts et dans le prompt des agents) ou Internal (ci-dessous).
Répertoire de travail et chemins relatifs
Le registre tient un répertoire de travail (FileSystemRegistry.WorkingDirectory, exposé par
IFileSystemService.WorkingDirectory) : le répertoire qu'un hôte a désigné par
SetWorkingDirectory(virtualPath) (un chemin absolu dans un mount visible des agents, sans segment
. ni ..) tant que son mount est enregistré, sinon /workspace quand un mount visible des
agents le réclame, sinon aucun. Les runners le désignent depuis
Orkeon:FileSystem:WorkingDirectory, sinon prennent /workspace, sinon /output ; un registre
d'exécution (ScopedMountComposition) garde celui du démarrage tant qu'il le monte encore.
- Un outil fichier (
file_read,file_write,edit_file,glob,grep,directory_read,directory_search,count_pattern, les outilsnode_*,edit_batch, et les outils de donnéescsv_reader,docx_reader,docx_writer,xlsx_reader,xlsx_writer,pdf_reader,xml_parser) résout un chemin relatif contre laworking_rootde l'agent quand il en a une, sinon contre le répertoire de travail (WorkingDirectoryResolver.Absolutize) :src/./lib/../stats.jsdevient/workspace/src/stats.js, chaque appel suivant vise ce chemin, et la réponse le renvoie. Le chemin devient absolu avant le contrôle des mounts et la garde de racine :../p2/xdepuis une racine/workspace/wt/p1est refusé comme hors de la racine. Sans répertoire de travail, un chemin relatif reste refusé.structural_searchetstructural_rewrite(paths),txt_searchetmdx_search(path) se résolvent de même, et chaque outil de cette liste,node_outlineetnode_readcompris, refuse un chemin hors de la racine de l'agent avant toute E/S. - Un
pathvide est refusé parpath is required: the absolute path of the file, e.g. /workspace/src/stats.js. - Un chemin qui ne commence par aucun mount est refusé avec la forme d'une adresse :
No mount found for virtual path 'x': a path starts with a mount: /workspace/src/stats.js. Available mounts: .... shell_commandsansworking_directorys'exécute dans la racine de l'agent, sinon dans le répertoire de travail ; unworking_directoryrelatif se résout de même. Il ne se replie jamais sur le premier mount qui accorde les droits : avec des mounts mais sans répertoire de travail, l'appel est refusé et nomme les mounts. Leworking_directoryrelatif devient absolu avant la garde de racine :../p2depuis une racine/workspace/wt/p1est refusé.- Un répertoire d'écriture (
FileSystemRegistry.WriteDirectory,IFileSystemService.WriteDirectory) reçoit unshell_commandd'écriture qui ne nomme aucunworking_directory, hors de toute racine d'agent, quand le répertoire de travail est refusé pour ses seuls droits. Une commande d'écriture (toute commande hors de la liste en lecture seule) exige tous les droits sur son répertoire de travail : lecture, écriture, création et suppression ; un/workspaceen lecture seule, comme dansorkeon forge, ne les accorde pas. Tout autre refus (aucun mount, une traversée, un chemin réservé par le runtime, le validateur de chemins) est rapporté tel quel. C'est le répertoire désigné parOrkeon:FileSystem:WriteDirectory(SetWriteDirectory, un chemin absolu sans segment.ni..dont les droits effectifs, surcharges de sous-arbre comprises, accordent l'écriture dans un mount visible des agents, faute de quoi l'hôte refuse de démarrer), sinon/outputquand un mount visible des agents y accorde l'écriture, sinon aucun. Il ne dépend jamais de l'ordre des mounts. Rien ne change quand le répertoire de travail accorde tous les droits (un/workspacemonté en lecture-écriture) ; sous une racine d'agent, aucun repli ; sans répertoire d'écriture, le refus nomme l'option. Les chemins relatifs des outils de fichiers se résolvent toujours contre le seul répertoire de travail. - Un registre d'exécution reporte les répertoires de travail et d'écriture du démarrage
(
WorkingDirectoryDesignation.CarryForward) tant qu'il les monte encore ; l'essai deorkeon forge(ForgeTrialScope.Compose) passe aussi par lĂ , sinon il prend son propre/workspaceou/output.
Racine de travail d'un agent et mount
Un agent peut déclarer une working_root (YAML ; AgentBuilder.WorkingRoot(string) ; .workingRoot(path)
sur un agent script de .ork.ts) : un chemin
virtuel tel que /workspace/.orkeon/worktrees/x qui doit se trouver sous un mount, faute de quoi
le run est refusé au démarrage par une erreur qui nomme la racine. C'est une intersection avec
les mounts, jamais une extension :
- les outils fichier (
FileToolBase.ResolveVirtualPath, viaAgentRootGuard) refusent, avant toute E/S, un chemin du même mount situé hors de la racine ; les autres mounts (/output,/tmp) gardent leurs propres droits ; shell_commandrefuse un répertoire de travail ou un argument de chemin hors de la racine, prend la racine pour répertoire de travail par défaut et y restreint les chemins confinés de son bac à sable (plus, quand la racine est un worktree git lié, les répertoires git par lesquels il commite : Confinement du shell) ;- un refus reprend la forme du refus VFS : les chemins physiques sont masqués.
La racine d'un agent script tient chaque outil que son corps exécute. ctx.llm.act et ctx.tools
s'exécutent en tant que l'agent. L'espace global tools ne sait pas quel agent l'appelle : il suit la
racine des agents ouverts tant qu'ils en partagent une, et refuse l'appel quand des agents de racines
différentes s'exécutent en même temps ; un corps qui s'exécute à côté d'autres appelle ctx.tools. Un
enfant lancé par spawn_agent ou ctx.spawnBackground sans racine propre s'exécute sous celle de son
parent, comme chaque crew.send ultérieur à cette instance.
Absente, rien ne change : les mounts seuls confinent l'agent.
Périmètre de fichiers d'un agent
Un agent peut aussi déclarer une liste filesystem: (YAML ; AgentBuilder.FileSystem(...) en C# ;
.filesystem([...]) sur un agent scripté .ork.ts) : les seuls chemins virtuels que ses outils peuvent
toucher. Une entrée est un chemin, ou {path, access} avec access parmi ro, rw, rwnd :
agents:
writer:
filesystem:
- /workspace/docs # les droits du mount Ă cet endroit
- path: /output/report
access: rwnd # réduit à lecture-écriture sans suppression
- Les droits viennent du mount : une entrée sélectionne et réduit (une intersection), n'étend jamais. Une
entrée hors de tout mount, ou un
accessque le mount n'accorde pas à cet endroit (ses surcharges de sous-chemin comprises), refuse le run au démarrage avec une erreur qui nomme l'agent et l'entrée ; de même un chemin relatif, un.., une entrée déclarée deux fois et une entrée dont l'accès n'accorde aucun droit. Une liste vide est refusée au chargement. - Un périmètre déclaré est exhaustif : pendant les appels d'outil de l'agent, le système de fichiers
refuse tout chemin hors de lui sur tous les mounts, dans sa forme de refus habituelle
(
Access denied for '<chemin virtuel>'), en nommant l'agent et son périmètre, et aucun autre mount. Le contrôle est dansFileSystemService.ResolveAndValidate, avant celui des mounts : tout outil qui passe par le VFS est tenu — les outils fichier,list_mounts(qui liste les entrées du périmètre avec les droits en vigueur),glob/grep, les outils de recherche, PDF et RAG, les pièces jointes e-mail et drive. Un chemin que le périmètre accorde mais qu'un mount refuse est refusé dans la même forme, en nommant le périmètre, jamais les autres mounts du run.shell_commandne lie dans son bac à sable que les entrées du périmètre, chacune avec les droits en vigueur. - Un chemin contrôlé est lu comme l'hôte le lit, et quand cette lecture est ambiguë le périmètre n'accorde
que ce que chaque lecture accorde. Hors Windows, une barre oblique inverse fait partie d'un nom
(
/output/notes\x.mdest le fichiernotes\x.mdde/output), sauf juste après la racine d'un mount, où le registre la prend pour un séparateur. L'entrée la plus spécifique est aussi cherchée sans la casse et sans les points ou espaces finaux d'un segment, si bien qu'un hôte insensible à la casse (/output/REPORT, ou/output/report.sous Windows) n'obtient jamais plus que ce que cette entrée accorde. Le périmètre peut ainsi refuser un chemin qu'un hôte sensible à la casse permettrait, jamais l'inverse. - Une énumération sous un périmètre (
directory_read,glob,grep, toute Ă©numĂ©ration du VFS) ne donne que les entrĂ©es qu'une lecture permettrait, chacune contrĂ´lĂ©e contre le pĂ©rimètre et les surcharges de sous-chemin du mount. Une suppression rĂ©cursive est refusĂ©e avant que rien ne soit supprimĂ© quand une entrĂ©e sous le rĂ©pertoire retientDelete(/outputrw,/output/reportro). - Les outils du graphe sĂ©mantique lisent un index qu'un autre run a pu remplir : pendant un appel Ă
périmètre, ils écartent chaque nœud dont le périmètre ne laisse pas l'agent lire le fichier, et tout ce
qui en nomme un (une arête, un chemin d'appel, un cycle, un résultat de recherche, une entrée de
complexité ou de centralité, la source d'un symbole, en cache ou non). Un nœud de monorepo ou de paquet
(un répertoire) reste visible sur le chemin d'une entrée du périmètre ; un nœud sans chemin virtuel (un
symbole externe, un nœud du plan d'une page Firefox) est gardé.
rag_ingestjuge chaque source qui n'est pas une adresse web, quelle que soit son écriture (relative, avec barres obliques inverses, enracinée à la Windows).start_jobécrit son journal de job sousjobs/d'un endroit où le périmètre laisse l'agent écrire (/output/jobsd'abord), sinon il est refusé en nommant le périmètre. - Seuls les appels d'outil de l'agent sont tenus. Les E/S propres du framework pendant le run (mémoire, connaissances, fichiers de sortie, manifestes) ne sont pas celles de l'agent et gardent les droits des mounts.
- Un enfant lancé depuis un appel d'outil d'un agent à périmètre (
spawn_agent, une tâche déléguée,ctx.spawnBackground, uncrew.sendultérieur à cette instance) s'exécute sous le périmètre de son parent ; son proprefilesystem:ne peut que le réduire, et une entrée hors du périmètre du parent ou au-delà de ses droits refuse le run de l'enfant. Un enfant qui n'en déclare aucun tient les droits de son parent sous son propre nom d'agent, que nomment ses refus et son prompt. - En
.ork.ts,ctx.delegatetransmet le périmètre de l'appelant comme le faitdelegate_work_to_coworker(la racine de travail de l'agent délégué reste la sienne). Un run que le script lance lui-même pendant que des agents tournent (crew.run,crew.runAgent,crew.runStream, celui d'une sous-crew) prend le périmètre des tentatives ouvertes, et il est refusé quand leurs périmètres diffèrent ;tools.*appelé depuis le code est tenu de la même façon. Les périmètres se comparent par ce qu'ils accordent, chaîne des parents comprise. Les hooksonAgentStart/onAgentStopd'un agent exécutent leurs outils sous sa racine de travail et son périmètre, un hook de crew sous ceux du premier agent ; un hook de cycle de vie dont les mounts refusent le périmètre de l'agent n'est pas exécuté, et un avertissement dit pourquoi.rag.ingestappelé depuis un corps à périmètre développe ses globs sous le périmètre et refuse une source hors de lui. - Avec une
working_root, la racine doit être dans le périmètre (sinon le run est refusé) : le périmètre dit ce que l'agent peut toucher, la racine où il travaille par défaut et où se résolvent les chemins relatifs. Déclarer les deux donne un répertoire par défaut à un agent à périmètre.
Absent, rien ne change : les mounts (et la working_root, s'il y en a une) confinent seuls l'agent.
Le système de fichiers dans le prompt
Un agent qui a un outil de fichiers (IBaseTool.UsesFileSystem : les outils fichier, de recherche, RAG,
de pièces jointes, email_parser, image_generation, firefox, index_codebase, incremental_reindex,
list_mounts, shell_command) reçoit une section ## File system dans son prompt système : les entrées
de son périmètre, sinon les mounts du run visibles des agents (jamais les internes), chacun avec ses
droits et ses surcharges de sous-chemin, triés par chemin virtuel pour que le prompt soit le même d'un run
à l'autre ; puis sa racine de travail, ou le répertoire contre lequel se résolvent les chemins relatifs
(dit hors du périmètre quand il l'est, pour que l'agent écrive chaque chemin en entier).
announce_mounts: false la retire, pour un agent ou, au niveau crew, pour chaque agent
qui ne fixe pas le sien (AgentBuilder.AnnounceMounts(false), .announceMounts(false)). Le prompt de
ctx.llm.act d'un agent scripté est celui du script et ne porte pas cette section : le corps la lit dans
ctx.fileSystem.prompt (le mĂŞme texte, "" quand aucun chemin n'est visible, quand l'agent n'a pas d'outil de
fichiers ou quand il fixe .announceMounts(false)) et la place oĂą il veut (AgentFileSystemPrompt.Render la rend
pour les deux formes).
Racines internes et accès privilégié
Un runner monte pour lui-mĂŞme quelques racines en montages internes
(Orkeon:FileSystem:InternalMounts, MountVisibility.Internal) : /llm-logs (les fichiers
d'échanges de --llm-log), /sandbox (où les sandboxes de code déposent ce qu'elles exécutent),
/state (le magasin de checkpoints), /runs (l'historique des runs), /llm-mock et
/llm-cassette (--llm-mock, --llm-record/--llm-replay) et /credentials (les jetons OAuth des comptes e-mail et drive — montée seulement quand un compte OAuth
de l'une des deux familles est déclaré). Le registre refuse un montage interne à tout appelant ordinaire et le signale comme
un chemin inexistant : aucun outil destiné aux agents ne peut l'atteindre ni même le nommer
(ADR-008). Les quelques composants qui
doivent y écrire demandent PrivilegedFileSystemAccess à la DI, par son nom : l'enregistreur des
échanges, les sandboxes de code et les magasins de jetons (FileSystemEmailTokenStore et
FileSystemDriveTokenStore, que l'hĂ´te des runners enregistre sur /credentials/email et
/credentials/drive). Ils passent toujours par le VFS. Le seul
System.IO brut sur ce chemin est la création, par le runner, du répertoire physique
credentials et de ses sous-répertoires email et drive (réservés au propriétaire sous Unix) avant
qu'aucun montage n'existe — du bootstrap Hosting/Runner*, une portĂ©e EXCEPTION-BOOTSTRAP dĂ©jĂ
ratifiée, pas une nouvelle catégorie. orkeon run refuse un montage utilisateur qui revendique
l'une de ces racines (EnsureReservedRootsAreFree, /state et /runs compris) ; chaque autre
point d'entrée refuse les racines qu'il se réserve (/crew et /sandbox pour --list-tools et
mcp serve), et tous refusent /credentials, quels que soient les comptes.
Mounts par scope (surcharge ambiante des mounts)
L'ensemble des mounts est un singleton défini au démarrage : AddOrkeonFileSystem construit un
FileSystemRegistry unique Ă partir de Orkeon:FileSystem:Mounts, et IFileSystemService est un
singleton au-dessus. C'est correct pour un runner mono-tenant, mais un hôte qui exécute plusieurs
crews dans un même processus (p. ex. un moteur d'exécution pilotant un profil différent par run)
doit pouvoir donner ses propres mounts à un flux d'exécution sans perturber les autres.
IFileSystemService ne peut pas devenir DI-scoped pour cela : des dizaines de singletons l'injectent,
donc une durée de vie scoped en ferait une dépendance captive. À la place, les mounts par scope sont
fournis par une surcharge ambiante — IFileSystemScope (enregistrĂ© en singleton, adossĂ© Ă
AsyncLocal<FileSystemRegistry?>, AsyncLocalFileSystemScope). Le singleton FileSystemService la
lit à chaque opération : il résout contre le registre ambiant quand un flux d'exécution en a
installé un, et contre le registre de démarrage sinon. AsyncLocal isole la valeur par flux de
contrĂ´le asynchrone, donc des runs concurrents ne voient jamais les mounts les uns des autres, et un
hôte qui n'entre jamais dans un scope conserve un comportement identique à l'octet près.
// Dans un scope de run : installer les mounts de ce run pour ce flux async uniquement.
var granted = grantedMountStrings.Select(FileSystemMount.Parse).ToList();
using var registry = ScopedMountComposition.ForExecution(bootRegistry, granted);
using var _ = fileSystemScope.Enter(registry); // restauré au dispose (imbrication supportée)
// Tout appel IFileSystemService sur CE flux async résout désormais contre `granted` ;
// les autres runs concurrents continuent de voir les mounts de démarrage.
Composer, jamais construire à la main. Entrer dans un scope REMPLACE le jeu de mounts —
ActiveRegistry vaut scope?.Current ?? boot, jamais une union — donc un registre bâti sur les
seuls dossiers d'une exécution emporte tout le jeu de boot avec lui pour la durée de ce flux.
ForExecution reporte donc les mounts de boot et laisse ceux de l'exécution les masquer aux
chemins virtuels qu'ils revendiquent ; la substitution plutĂ´t que l'addition est la raison d'ĂŞtre
du mécanisme, puisque deux crews recevant chacun /output sur des dossiers différents est
précisément ce qu'un registre plat ne sait pas exprimer.
Les deux moitiés du jeu de boot doivent survivre, pour des raisons différentes. Les mounts
internes (RunnerVirtualRoots : /llm-logs, /sandbox, /state, /runs, /credentials, …) relèvent de la confidentialité : les
perdre arrête la journalisation des échanges, les deux sandboxes de code et le magasin de jetons
e-mail, et fait tomber IsUnderInternalMountUnsafe, le contrĂ´le qui empĂŞche l'un d'eux de gagner
une seconde adresse atteignable par un agent via un mount de l'exécution. Les mounts agent-facing portent tout
autant : orkeon-host monte le dossier de chaque crew hébergé sous /crews puis charge le crew
par ce chemin virtuel, depuis l'intérieur du scope. Un registre composé des seuls mounts
de l'exécution laisserait le crew injoignable, et ExistsAsync, qui avale le refus, le rendrait
comme un échec de run générique.
Qui en entre un aujourd'hui. orkeon-host est le seul hôte de runner livré qui le
fasse, une fois par crew hébergé, depuis Orkeon:Host:Crews:*:Mounts — deux crews hébergés peuvent
donc adresser chacun son /output sur des dossiers différents, ce que l'unique registre de boot,
plat, ne sait pas exprimer. L'essai de orkeon forge (ForgeTrialScope) en entre un aussi, sur ses dossiers d'essai. Tous les autres runners gardent les mounts de boot : un processus par
lancement rend la question sans objet chez eux.
Les gardes s'appliquent aux mounts scopés exactement comme aux mounts de démarrage, car elles
s'exécutent à chaque opération sur le registre actif : le registre applique les droits de mount + le
confinement contre la traversée de chemin, et IPathValidator applique indépendamment les contrôles
racine-workspace / chemins bloqués / extensions (PathSecurity:DefaultWorkspaceRoot,
AdditionalAllowedDirectories). Un dossier accordé dans
Orkeon:Host:Crews:*:Mounts est une entrée du démon : il est lisible où qu'il soit, sans
--allow-external-mounts. L'appelant possède
la durée de vie du FileSystemRegistry scopé (Enter ne le dispose pas — le disposer soi-même,
comme ci-dessus).
Comportement en CI
Les sept diagnostics (ORKVFS001–ORKVFS007) sont tous des erreurs, donc la CI bloque tout merge qui réintroduit un accès fichier System.IO, un StreamReader/StreamWriter par chemin, un Path.GetFullPath sur entrée utilisateur, ou un IFileSystemService nullable dans le code du framework sans attribut [SuppressVfsCompliance] justifié.