Context Surfaces
What a running system emits that an agent can read

Table of Contents

1. What is a surface?

Look at the word. Sur-face: the face a thing turns outward. Not the thing. The part of it you can be in contact with.

A running system has an interior. Objects, threads, a heap, whatever plan the database made. You are not in there. You were never in there. What you have is whatever the system turns outward, and that is all you have ever had.

So a surface is not a view of the system. It is the part of the system that faces you.

1.1. Acting and knowing are two things

We have a word for giving an agent capability. Tools. Give it a shell, a file reader, an editor. Having done that, we say it has access to the system, and we move on.

That sentence has two things braided into it.

One is acting: doing something to the system. The other is knowing: having some warrant about what the system is doing. We conflate them because one mechanism delivers both — the shell edits and the shell reads — so we stop distinguishing, and then we are surprised when an agent with every tool available still cannot say what went wrong.

The shell is not the surface. The shell is how you reach one. A log is a surface. A shell is a hand.

1.2. Reading and asking are two things

Same move, one level down.

You can read a log. You can ask a REPL. Both hand you information, so we file them together.

Consider what happens when you ask. You formulate the question. The question comes out of what you already believe. The answer comes back shaped to it. You have learned something, strictly inside the boundary you drew before you started.

Now the log. Nobody asked it anything. It records what happened, including the parts you did not think to wonder about. The log is indifferent to your model, which is exactly its value: it is the only thing in the room that can contradict you about something you were not tracking.

That is the distinction. Not reading versus writing. Told versus asked.

A surface tells you. Interrogation is what you do afterwards, once you know enough to have a question worth asking.

1.3. This is not a ranking

A REPL is more powerful than a log. It is also immediate, and interactive, and it is right there. It is easy.

Emitted context is the simple one. One thing, doing one thing, regardless of you and regardless of whether anyone is watching. Easy and simple are different, and given the choice we take easy, which is how a debugger sits unopened in a dependency list for an entire working session.

1.4. A surface is a surface for somebody

Last one. Surfaces are not a property of the system alone.

Two workers, one machine, same running process. One holds the key and one does not. For the first there is a surface. For the second there is state, and a closed door, and no amount of diligence opens it.

The door is not a bug. Read it as a missing surface and you know what to do. Read it as a fault and you will go looking for a way around it.

2. The definition

A context surface is a local state source that a worker can read from its own tools, and which creates context about a running system.

Read-only by default. The surface emits; the worker reads. That is the whole primary case.

3. The cut is emitted versus elicited

Not read versus write. The useful line is between context that arrives and context you have to go and get.

A log is written whether or not anyone asks. A hook stream fires on events nobody anticipated. clj-kondo produces an analysis of a codebase the worker has not read. A rendered accessibility tree describes a page as it actually is. Each of these yields context before a question has been formulated — which matters, because the questions a worker knows to ask are bounded by what it already believes.

Evaluating a form in a REPL is the other thing. So is poking a console, starting and stopping components, running a migration, adding a fault, or driving property-based tests against the system under review. These are secondary, and they are secondary together, including the ones that only read: an elicited answer requires the worker to have known what to ask.

The distinction is not a ranking of usefulness. A REPL is more powerful than a log. It is a claim about what makes something a surface: the primary capability is producing context unprompted.

4. Not an agent harness

The two are routinely conflated and they are different layers.

  harness context surface
answers how does the worker act what can the worker know
examples tool calling, the agent loop, sessions, the model logs, traces, diagnostics, a hook stream
read/bash/edit/write these are the harness these are how you reach a surface, not the surface

A harness supplies the call mechanism. Surfaces are what there is to read through it. The harness literature — Microsoft Learn, LangChain, Comet, Atlan, and at least two arXiv entries — defines harness carefully and has no term for the other half.

The practical consequence: adding a harness capability does not add context. An agent with bash could always have attached a debugger. It did not, because bash returns text once and the process is gone.

5. Visibility is relative to identity

A surface is a surface for a given identity in a given execution context. The same state is available to one worker and absent to another on the same machine.

A worked example from this repository, on 2026-09-26: a deploy box was a surface for the human, who held the key, and not for the agent, which did not. The Permission denied was a privilege boundary working exactly as designed. The correct reading was a missing surface, not a fault to route around.

Two consequences follow.

  • The inventory is enumerable. The service connectors attached to a session, plus the local ports and processes its identity can reach, are a census of what that worker can know.
  • A connector that fails to connect is a surface that is down, while the state behind it is untouched. Those are different failures and want different responses.

6. Latent state is not a surface

Something installed, documented, and unreachable from where the worker actually works is latent state.

FlowStorm — a Clojure debugger — sat in a project's deps.edn for an entire working session, present and never used. The capability existed. Its GUI-first presentation put it outside the surface set of an agent working in a terminal. Calling that a failure of diligence is precisely the misattribution Norman warns against: the gulf is a property of the system's design, not the actor's competence.

7. Why local

Triage of a remote system through a vendor's API — inside a retention window, query language and rate limits set elsewhere — is a different problem with different constraints. So is telemetry shipped off the box. Both matter; neither is this term. Keeping local in the definition is what stops the word expanding until it means "context", which would make it useless.

8. The enumerated set

What a worker reads, what it can drive as a secondary capability, and the tools that provide each.

Surface Reads (primary) Drives (secondary) Tools
source files, clj-kondo analysis, clojure-lsp diagnostics edits with paren-repair hooks clj-kondo, clojure-lsp, paren-repair hook
REPL eval results, var metadata, docstrings eval forms, reload namespaces nREPL, an eval client or MCP bridge
running instance system map, schema instrumentation errors, tap> start and stop components, change config a system library, malli.dev/start!
database schema, rows, query plans migrations, fixture seeding next.jdbc, HoneySQL
DOM accessibility tree, console, network clicks, form input, scripted journeys a browser driver, Playwright, Bombadil
load latency histograms, error rates fixed-rate and ramp profiles k6, Gatling
faults active toxics per link add and remove toxics Toxiproxy
OpenTelemetry signals traces, metrics, logs, alert state synthetic load on the receiver OTel agent, an OTLP receiver, telemetrygen
agent session sightings for thirty hook events none — measurement only hook script, crowsnest receiver

The last row is the clean instance of the definition. There is nothing to drive: the surface exists solely to create context, and it does so by capturing events the worker did not ask about.

9. Related

10. What the word already means

WordNet 3.1 gives surface six noun senses, three verb senses and one adjective sense. Three of them bear on the term, and one of them is a warning.

Two senses put it under boundary:

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

Sense 2's hypernym chain is boundary, bound, bounds > =extremity > =region, part > =location. That corrects the etymological gloss above. Sur-face is where the word comes from; the sense the language actually carries is boundary — the limit of a thing. A boundary is what you are on the other side of, which is the point.

The third is the one worth having:

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

Its hypernym is public knowledge, general knowledge > =cognition > =abstraction. A different branch of the hierarchy entirely: not a physical object, a kind of knowledge. English already has "surface" meaning information brought into the open, and classifies it as cognition. The term here is not a metaphor being stretched; it is that sense, applied.

The verb agrees. Sense 3: come on, come out, turn up, surface, show up --- appear or become visible; make a showing. To surface is to become visible, intransitively, without anyone doing it to you. That is the emitted-not- elicited distinction sitting inside the word.

10.1. The sense to guard against

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

Its hypernym is aspect, facet. This is the baggage: surface also means shallow, and specifically shallow in contrast to what is really going on. Any reader who lands on sense 4 will hear "context surface" as "the superficial part," which inverts the claim.

Nothing can be done about that except to say it. The term means senses 1, 2 and 5 — a boundary, and information brought into the open — and explicitly not sense 4. A borrowed word arrives with all of its senses, and the ones you did not want do not go away because you were thinking of a different one.

11. Prior art, and a caution

Two web searches found the constituent mechanisms named individually — filesystem, git, memory files, context injection, the filesystem as a "shared ledger" — and no collective noun for them. Surface is borrowed from attack surface and API surface, where it means the set of things exposed. The compound is local and means what is defined above.

While looking, two phrases came back reported as established: "durable state surfaces" and "stable evidence surfaces". Reading the two pages showed neither occurs in either. The sources say "durable state" as a property of filesystem and git, and separately "a surface where multiple agents and humans can coordinate through shared files". Both reported phrases were fusions produced by a search summary, and they were repeated here as quotations before being checked.

Recorded because it is the failure this page's own argument predicts: a summary is elicited context, shaped by the question asked. The source is the surface.