Surfaces de contexte
Ce qu'un système en marche émet et qu'un agent peut lire

Table des matières

Version originale : English

1. Qu'est-ce qu'une surface ?

Sur-face : la face qu'une chose tourne vers l'extérieur, pas la chose. La partie avec laquelle on peut être en contact.

Un système en marche a un intérieur. Des objets, des threads, un tas, le plan qu'a fait la base de données. On n'y a jamais été. On a ce que le système tourne vers l'extérieur. On n'a jamais rien eu d'autre.

Une surface n'est pas une vue du système. C'est la partie du système qui vous fait face.

1.1. Agir et savoir sont deux choses

Pour donner une capacité à un agent, on a un mot : les outils. On lui donne un shell, un lecteur de fichiers, un éditeur. Ensuite on dit qu'il a accès au système, et on passe à autre chose.

Cette phrase mêle deux choses.

La première est agir : faire quelque chose au système. La seconde est savoir : avoir une justification sur ce que fait le système. On les confond parce qu'un seul mécanisme fournit les deux. Le shell modifie et le shell lit. On cesse de distinguer. Puis on s'étonne qu'un agent qui a tous les outils ne sache toujours pas dire ce qui a mal tourné.

Le shell n'est pas la surface. C'est le moyen d'en atteindre une. Un log est une surface. Un shell est une main.

1.2. Lire et demander sont deux choses

On lit un log. On interroge un REPL. Les deux donnent de l'information. On les range ensemble.

Quand on demande, on formule la question. La question vient de ce qu'on croit déjà. La réponse revient à sa forme. On a appris quelque chose, mais seulement à l'intérieur de la limite que vous avez tracée avant de commencer.

Personne n'a rien demandé au log. Il enregistre ce qui s'est passé, y compris ce qu'on n'a pas pensé à se demander. Il est indifférent à votre modèle. C'est sa valeur. C'est la seule chose dans la pièce qui peut vous contredire sur ce que vous ne suiviez pas.

La distinction n'est pas lire contre écrire. C'est dit contre demandé.

Une surface vous dit. L'interrogation vient après, quand on en sait assez pour avoir une question qui vaut d'être posée.

1.3. Ce n'est pas un classement

Un REPL est plus puissant qu'un log. Il est immédiat, interactif, sous la main. Il est facile.

Le contexte émis est le simple. Une chose qui fait une chose, sans égard pour vous, que quelqu'un regarde ou non. Facile et simple diffèrent. Devant le choix, on prend le facile. C'est ainsi qu'un debugger reste fermé dans une liste de dépendances pendant toute une session de travail.

1.4. Une surface est une surface pour quelqu'un

Une surface n'est pas une propriété du seul système.

Deux workers, une machine, le même processus en marche. L'un a la clé, l'autre non. Pour le premier, il y a une surface. Pour le second, il y a de l'état et une porte fermée. Aucune diligence ne l'ouvre.

La porte n'est pas un bug. Si on la lit comme une surface absente, on sait quoi faire. Si on la lit comme une panne, on cherche à la contourner.

2. La définition

Une surface de contexte est une source d'état locale qu'un worker peut lire avec ses propres outils, et qui crée du contexte sur un système en marche.

Lecture seule par défaut. La surface émet. Le worker lit. C'est tout le cas primaire.

3. La coupure : émis contre sollicité

Pas lecture contre écriture. La ligne utile sépare le contexte qui arrive et le contexte qu'il faut aller chercher.

Un log s'écrit que quelqu'un demande ou non. Un flux de hooks se déclenche sur des événements que personne n'a prévus. clj-kondo produit une analyse d'une base de code que le worker n'a pas lue. Un arbre d'accessibilité rendu décrit une page telle qu'elle est. Chacun donne du contexte avant qu'une question soit formulée. Cela compte : les questions qu'un worker sait poser sont bornées par ce qu'il croit déjà.

Évaluer une forme dans un REPL, c'est l'autre chose. De même fouiller une console, démarrer et arrêter des composants, lancer une migration, injecter une faute, ou lancer des tests property-based contre le système étudié. Tout cela est secondaire, ensemble, même ce qui ne fait que lire. Une réponse sollicitée exige que le worker ait su quoi demander.

La distinction dit ce qui fait une surface : sa capacité primaire est de produire du contexte sans qu'on le demande.

4. Pas un harness d'agent

On confond souvent les deux. Ce sont des couches différentes.

  harness surface de contexte
répond à comment le worker agit ce que le worker peut savoir
exemples tool calling, la boucle d'agent, les sessions, le modèle logs, traces, diagnostics, un flux de hooks
read/bash/edit/write c'est le harness c'est le moyen d'atteindre une surface, pas la surface

Un harness fournit le mécanisme d'appel. Les surfaces sont ce qu'il y a à lire à travers lui. La littérature sur les harness (Microsoft Learn, LangChain, Comet, Atlan, au moins deux entrées arXiv) définit harness avec soin. Elle n'a pas de terme pour l'autre moitié.

Ajouter une capacité au harness n'ajoute pas de contexte. Un agent avec bash a toujours pu attacher un debugger. Il ne l'a pas fait, parce que bash rend du texte une fois, puis le processus disparaît.

5. La visibilité dépend de l'identité

Une surface est une surface pour une identité donnée dans un contexte d'exécution donné. Le même état est accessible à un worker et absent pour un autre, sur la même machine.

Le 2026-09-26, dans ce dépôt, une machine de déploiement était une surface pour l'humain, qui avait la clé. Elle ne l'était pas pour l'agent, qui ne l'avait pas. Le Permission denied était une frontière de privilèges qui marchait comme prévu. Il fallait lire une surface absente, pas une panne à contourner.

  • L'inventaire est énumérable. Les connecteurs de service attachés à une session, plus les ports et processus locaux que son identité atteint, recensent ce que ce worker peut savoir.
  • Un connecteur qui n'arrive pas à se connecter est une surface en panne. L'état derrière reste intact. Ce sont deux pannes différentes. Elles demandent des réponses différentes.

6. L'état latent n'est pas une surface

Une chose installée, documentée, et hors d'atteinte de l'endroit où travaille le worker, c'est de l'état latent.

FlowStorm, un debugger Clojure, est resté dans le deps.edn d'un projet pendant toute une session de travail. Il était là. Personne ne s'en est servi. Son interface d'abord graphique le mettait hors des surfaces d'un agent qui travaille dans un terminal. Parler d'un manque de diligence, c'est précisément l'erreur d'attribution contre laquelle Norman met en garde. Le gouffre (gulf) tient à la conception du système, pas à la compétence de l'acteur.

7. Pourquoi local

Trier un système distant par l'API d'un fournisseur est un autre problème, avec d'autres contraintes. La fenêtre de rétention, le langage de requête et les limites de débit sont fixés ailleurs. La télémétrie envoyée hors de la machine aussi. Les deux comptent. Aucun n'est ce terme. Local dans la définition empêche le mot de s'étendre jusqu'à signifier « contexte ». Il ne servirait plus à rien.

8. L'inventaire

Surface Lit (primaire) Pilote (secondaire) Outils
source fichiers, analyse clj-kondo, diagnostics clojure-lsp modifications avec hooks paren-repair clj-kondo, clojure-lsp, hook paren-repair
REPL résultats d'eval, métadonnées de var, docstrings évaluer des formes, recharger des namespaces nREPL, un client d'eval ou un pont MCP
instance en marche system map, erreurs d'instrumentation de schéma, tap> démarrer et arrêter des composants, changer la config une bibliothèque system, malli.dev/start!
base de données schéma, lignes, plans de requête migrations, chargement de fixtures next.jdbc, HoneySQL
DOM arbre d'accessibilité, console, réseau clics, saisie de formulaire, parcours scriptés un driver de navigateur, Playwright, Bombadil
charge histogrammes de latence, taux d'erreur profils à débit fixe et en rampe k6, Gatling
fautes toxics actifs par lien ajouter et retirer des toxics Toxiproxy
signaux OpenTelemetry traces, métriques, logs, état des alertes charge synthétique sur le récepteur agent OTel, un récepteur OTLP, telemetrygen
session d'agent sightings pour trente événements de hook aucun — mesure seulement script de hook, récepteur crowsnest

La dernière ligne est le cas pur de la définition. Il n'y a rien à piloter. La surface n'existe que pour créer du contexte. Elle le fait en capturant des événements sur lesquels le worker n'a rien demandé.

9. Voir aussi

10. Ce que le mot veut déjà dire

WordNet 3.1 donne à surface six sens de nom, trois sens de verbe et un sens d'adjectif. Trois touchent au terme. Un quatrième est un avertissement.

Deux sens le rangent sous boundary (limite) :

1. (90) the outer boundary of an artifact or a material layer constituting
        or resembling such a boundary
2. (36) the extended two-dimensional outer boundary of a three-dimensional
        object

La chaîne d'hyperonymes du sens 2 est boundary, bound, bounds > =extremity > =region, part > =location. Cela corrige la glose étymologique plus haut. Sur-face est l'origine du mot. Le sens que porte la langue est boundary : la limite d'une chose. On est toujours de l'autre côté d'une limite.

Le troisième :

5. open, surface -- information that has become public;
   "the facts had been brought to the surface"

Son hyperonyme est public knowledge, general knowledge > =cognition > =abstraction. C'est une autre branche de la hiérarchie : pas un objet physique, une sorte de savoir. Le terme n'étire pas une métaphore. Il applique ce sens.

Le verbe dit la même chose. Sens 3 : come on, come out, turn up, surface, show up --- appear or become visible; make a showing. Faire surface, c'est devenir visible, sans complément, sans que personne vous le fasse. La distinction émis/sollicité est dans le mot.

10.1. Le sens à écarter

4. (4) a superficial aspect as opposed to the real nature of something;
   "it was not what it appeared to be on the surface"

Son hyperonyme est aspect, facet. C'est le bagage. Surface veut aussi dire superficiel, et superficiel par opposition à ce qui se passe vraiment. Un lecteur qui tombe sur le sens 4 entendra « surface de contexte » comme « la partie superficielle ». Cela inverse la thèse.

On ne peut que le dire. Le terme veut dire les sens 1, 2 et 5 : une limite, et une information mise au jour. Pas le sens 4. Un mot emprunté arrive avec tous ses sens. Ceux dont on ne voulait pas ne partent pas parce qu'on pensait à un autre.

11. Antériorité, et une mise en garde

Deux recherches web ont trouvé les mécanismes nommés un par un : système de fichiers, git, fichiers mémoire, injection de contexte, le système de fichiers comme « shared ledger ». Elles n'ont trouvé aucun nom collectif. Surface vient de attack surface et API surface, où le mot désigne l'ensemble de ce qui est exposé. Le composé est local. Il veut dire ce qui est défini plus haut.

Pendant la recherche, deux expressions sont revenues présentées comme établies : « durable state surfaces » et « stable evidence surfaces ». On a lu les deux pages. Aucune des deux expressions n'y figure. Les sources disent « durable state », comme propriété du système de fichiers et de git. Ailleurs elles disent « a surface where multiple agents and humans can coordinate through shared files ». Les deux expressions étaient des fusions produites par un résumé de recherche. Elles ont été reprises ici comme citations avant d'être vérifiées.

On le consigne parce que c'est l'échec que prédit l'argument de cette page. Un résumé est du contexte sollicité, formé par la question posée. La source est la surface.

Vu à