Skip to content

About

What an interface actually showed a person, in a form an agent can read.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Semantic Surface

A serializable, medium-independent record of what an interface has actually presented to a person, and of what their attention is on.

It answers one question: what is the user looking at right now, and what does "this" refer to?

The problem

Ask an assistant to "restart this one" and it has to work out what "this one" is. There are two usual ways to find out, and both are bad.

Hand it a screenshot, and it reads pixels: it recovers a picture of the screen but none of the identity behind it, so a name on screen is just a string that resembles a name.

Hand it the application's database, and it has the identities but not the attention: it can see every cluster the person owns and no reason to prefer the one they are looking at.

A Semantic Surface snapshot is neither. It is a small, declared, validatable document in which the interface states what it put in front of the person — the areas on screen, the entities they name, the readings they showed, and which of those the user's attention is on. The interface already knows all of it. The snapshot is simply the interface saying it out loud, instead of leaving an agent to infer it.

What a snapshot is not

It is descriptive, never authoritative. A snapshot does not say what the current truth of the domain is, which operations are available, who may perform them, or how they are carried out. Every entity in it is a reference to be resolved through a real tool before anything is acted on.

That boundary is the whole safety argument. A snapshot can be stale, partial, or supplied by a browser, and none of that matters as long as nothing is ever decided from it. It narrows the question; it never answers it.

Where it is used

Semantic Surface was designed at Flui, and Flui is where it runs today.

The Flui dashboard produces a snapshot for each of its screens: which clusters, applications, keys or policies are on display, what state each was shown in, and which one the person has selected. The Flui assistant consumes those snapshots, so that a question asked in front of a screen is understood in terms of what that screen was showing.

The specification's annexes carry worked examples drawn from a real producer, and they are worth a word, because they keep one distinction clear. The scheme a reference is written in, the namespace an extension key sits under, the address that identifies the schema — those belong to whoever produces the snapshot, not to the contract. What the specification fixes is how a reference and an extension key are formed. A second implementation coins its own and is no less conformant.

The contract

The contract is the wire format: the shape of a snapshot as it travels, not any particular language binding.

  • Normative specification: docs/agent-surface/semantic-surface-core-v0.2.md
  • JSON Schema (draft 2020-12): docs/agent-surface/semantic-surface.schema.json

Sections 1 to 13 of the specification are normative; the annexes are informative. The TypeScript types in this package are a convenient rendering of the same contract, and where they and the schema disagree, the schema wins.

One further document travels with the package for provenance only, and is not normative: the decision record answering the technical review of v0.1. The two documents behind it were internal working papers and are not distributed.

What this package provides

A reference implementation of the consumer side — the half that receives a snapshot and has to decide whether to trust it — in three layers.

Acceptance caps the size of the payload and validates it against the schema. A snapshot that fails is dropped rather than raised: a defect in the Surface must never be allowed to fail the user's question.

Semantic validation makes the cross-document checks a schema cannot: broken references, cycles, duplicate identifiers, counts larger than the totals they belong to, timestamps that are well formed but not real instants, revisions that do not advance.

Rendering turns a snapshot into a bounded, deterministic block of text for a prompt. Deterministic matters more than it sounds: no clock is ever read, so the same snapshot always renders to the same bytes. Every string that could have come from a machine is escaped on the way in, because a resource name is data and must never be able to end the block and start giving instructions.

Producers — the code inside an application that builds a snapshot — are deliberately not here. They are written against the schema, in whatever language the interface itself is written in.

Install

npm install @flui-cloud/semantic-surface

Licence

Apache-2.0. See LICENSE.

About

What an interface actually showed a person, in a form an agent can read.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages