@flui-cloud/semantic-surface 0.1.0

package/docs/agent-surface/semantic-surface-core-v0.2.md

@@ -0,0 +1,911 @@
+# Semantic Surface — Core Specification
+
+**Version:** 0.2
+**Status:** Normative draft — implementable, validatable, measurable. Not yet submitted as a public standard.
+**Date:** 2026-08-05
+**Schema:** [`semantic-surface.schema.json`](semantic-surface.schema.json)
+**Supersedes:** the v0.1 draft, `vops-semantic-surface-spec.md`.
+**Built from:** v0.1, the technical review of it (`semantic-surface-v0.1-review.md`) and the response decision record (`semantic-surface-response-to-review-v0.2.md`). Where they conflict, **this document prevails**. The v0.1 draft and its review were internal working documents of the sponsoring product and are not distributed here; they are cited for provenance only.
+
+---
+
+## How to read this document
+
+The keywords **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT** and **MAY** carry their usual meaning in technical specifications: MUST is a conformance requirement, SHOULD is a strong recommendation that may be departed from with reason, MAY is optional.
+
+Sections **§1–§13 are normative**. **Annex A and Annex B are informative** and do not contribute to conformance.
+
+The contract of this specification is the **wire format** (§4): the serializable JSON form of a snapshot. The TypeScript interfaces are a convenient rendering of that same contract, not the contract itself. The runtime APIs (§10) are **not** required for conformance.
+
+---
+
+## 1. Purpose, definition and non-goals
+
+### 1.1 Canonical definition
+
+> **The Semantic Surface is a serializable, medium-independent representation of the user's current attention and of what the interface has actually presented to them.**
+
+It answers exactly one question: **what is the user looking at right now, and what does "this" refer to?**
+
+It does not answer — and MUST NOT attempt to answer — what the current truth of the domain is, which operations are available, who is authorised to perform them, or how they are executed.
+
+### 1.2 What a Surface MAY describe
+
+- current route or view, and active scopes;
+- primary entity, selections, attention;
+- active modes: tabs, filters, time window, sort order;
+- open overlays;
+- semantic state of the view: loading, error, no results, truncation;
+- values **actually presented** to the user, with the time the underlying reading was taken;
+- references (`resourceRef`) for retrieving authoritative data.
+
+### 1.3 What a Surface MUST NOT become
+
+- a replica of the application store;
+- a dump of API responses;
+- a complete domain model;
+- a capability catalogue;
+- an authorisation system;
+- a representation of clicks, or a navigation model;
+- a browser-automation engine;
+- a second accessibility tree.
+
+### 1.4 Positioning
+
+The Surface describes **context**. Operational catalogues — MCP on the server side, and in-browser proposals such as WebMCP — describe and execute **actions**. They are complementary planes:
+
+```text
+Semantic Surface  →  what has been presented, and what "this" refers to
+MCP / WebMCP      →  which tools exist, who may use them, how they run
+```
+
+This specification MUST NOT introduce proprietary browser APIs and MUST NOT define tools. The format is transport-independent (§11), so that it can also travel over channels standardised in the future.
+
+### 1.5 Explicit non-goals
+
+**Multimodality.** The term carries three readings; this specification normalises exactly one:
+
+| Reading | Status |
+|---|---|
+| (a) The agent combines several input sources — semantics, pixels, DOM, APIs | **Out of scope, but anchorable.** It is a property of the host, not of the producer. The specification provides only the optional anchor of §11.4 |
+| (b) Several user→agent channels: chat, voice, command, gesture | **Explicit non-goal.** It belongs to the assistant integration |
+| (c) Several surfaces of the same product — web, SSR, CLI, TUI, voice — exposing the same attention model | **This is the reading being normalised.** A standard can only normalise what the producer controls |
+
+**Agent→UI interaction.** v0.2 is **purely descriptive**: the Surface does not execute, navigate or prefill. The exclusion is deliberate and already bounded: a future extension registered as **SS-ATTENTION** (§13.3) MAY let an agent *request* that the user's attention be moved to, or marked on, an element the Surface names, and MUST NOT under any circumstance perform domain actions, submit forms or modify data.
+
+---
+
+## 2. Conceptual model
+
+### 2.1 The three planes
+
+```text
+Semantic Surface
+        │  describes UI context                        (not authoritative)
+        ▼
+Assistant / Planner
+        │  interprets intent and selects a tool
+        ▼
+MCP Server / Backend
+        │  authorises, approves, validates, executes, audits   (authoritative)
+        ▼
+Application Services / Infrastructure
+```
+
+Preserving this separation is the primary condition for the project not to become a second UI framework, a browser-automation system, or a new state manager.
+
+### 2.2 Roles
+
+- **Producer** — the application that builds the snapshot. It is solely responsible for redaction (§8.2).
+- **Consumer** — whoever reads the snapshot: assistant, planner, inspector, diagnostic tool.
+- **Assistant host** — whoever composes the prompt and encapsulates the snapshot as untrusted data (§8.4).
+
+### 2.3 Terms
+
+- **Scope** — a semantically meaningful region: a page, a region, a selection, a list, a form, an overlay. It does not necessarily coincide with a UI component.
+- **Attention** — the scope, and optionally the entity, the user's attention is directed at. It is a list ordered by salience.
+- **Entity reference** — a stable reference to a domain entity (§5).
+- **Observation** — a piece of information **presented** to the user (§3, §4.6).
+- **Snapshot** — the JSON materialisation of the Surface at one instant (§4).
+- **Revision** — a monotonic counter identifying the state of the Surface (§7).
+
+### 2.4 Contribution rule
+
+A component, region or page controller contributes to the Surface **only** when it: introduces or represents a domain entity; adds relevant observations; changes selection or attention; represents an independent operational region; or opens a transient context (an overlay).
+
+Purely visual elements MUST NOT register anything.
+
+A UI that **observes** the Surface — an assistant panel, an inspector, a debug overlay — MUST NOT contribute scopes either. It would describe itself into the description it is reading, and an open assistant would appear as the thing the user is attending to.
+
+---
+
+## 3. Data admission rules
+
+### 3.1 Principle: presented, not asserted
+
+An observation in the Surface **does not assert** that a value is authoritative now. It asserts that it **was presented to the user in that form at that moment**. This is the distinction that allows backend-derived data to be included without duplicating the backend.
+
+### 3.2 Admission criteria
+
+Information MAY enter the Surface when it meets at least one of these criteria:
+
+1. it exists only in the UI session: selection, attention, filter, mode, overlay;
+2. it describes **how** a value was presented to the user;
+3. it is required to resolve a deictic reference — "this server", "the selected one";
+4. it states the semantic state of the view: loading, error, empty, truncated;
+5. it carries a reference for retrieving the complete or current value from the authoritative source.
+
+### 3.3 Exclusion criteria
+
+Information MUST NOT enter when:
+
+- it is better and unambiguously retrievable from an authoritative tool;
+- it is not relevant to the current view or attention;
+- it duplicates large backend structures;
+- it contains secrets or unnecessary personal data;
+- it was produced **solely to explain the page to the model**, and is not part of the product.
+
+### 3.4 Anti-drift rule (normative)
+
+There MUST NOT be two state structures kept in sync by hand:
+
+```text
+                Application state
+                        │
+        ┌───────────────┴───────────────┐
+     UI rendering              Surface materialisation
+```
+
+A semantic provider MUST read the same reactive state the rendering reads. It MUST NOT copy values into a parallel structure.
+
+*Why this is normative:* it leaves only one possible kind of drift — **coverage** drift, a view with no semantic definition — which is mechanically detectable with a lint over the main routes and with the inspector. **Truth** drift — a snapshot asserting a value the UI no longer shows — would be invisible until it causes harm, and it is how artefacts of this kind historically rot.
+
+### 3.5 Free text
+
+| Case | Rule |
+|---|---|
+| Text actually shown to the user | **Allowed**, subject to a length limit and `source` |
+| A summary produced by the backend, part of the product, tested, and also shown to the user | **Allowed with care**, with `source: "api"` |
+| Text written by the semantic provider to steer the model | **FORBIDDEN** |
+
+An example of what is forbidden: `"This server looks badly degraded and should be restarted."` — an instruction disguised as an observation, not part of the product, untested, feeding an agent's prompt directly.
+
+Free text MUST respect: the length limits of §9, no HTML or arbitrary markup, no secrets, no operational instructions.
+
+---
+
+## 4. Wire format (normative)
+
+A snapshot MUST be serializable JSON and MUST validate against [`semantic-surface.schema.json`](semantic-surface.schema.json).
+
+```ts
+interface SurfaceSnapshot {
+  schemaVersion: "0.2";
+
+  app: {
+    id: string;                    // producer namespace, e.g. "vops"
+    version?: string;
+  };
+
+  surface: {
+    id: string;
+    route?: string;
+    revision: number;              // monotonically increasing integer
+    generatedAt: string;           // ISO 8601, when the snapshot was produced
+    locale?: string;
+    truncated?: boolean;           // true when the budget dropped something
+  };
+
+  attention: AttentionTarget[];    // ordered by salience, first is primary
+  scopes: SemanticScopeSnapshot[]; // flat list, hierarchy via parentId
+
+  extensions?: Record<string, unknown>; // namespaced keys, see §13.2
+}
+
+interface AttentionTarget {
+  scopeId: string;
+  entityRef?: string;
+  reason?: string;                 // reserved values in §6.3
+}
+
+interface SemanticScopeSnapshot {
+  id: string;
+  parentId?: string;
+  kind: string;                    // reserved values in §6.2
+  label?: string;
+
+  entities?: EntityReference[];
+  observations?: Observation[];
+
+  state?: {
+    loading?: boolean;
+    error?: boolean;
+    errorCode?: string;            // a code, never the free-text error message
+    empty?: boolean;
+  };
+
+  completeness?: {
+    shown: number;
+    total?: number;
+    filtered?: boolean;
+    truncated?: boolean;
+  };
+
+  extensions?: Record<string, unknown>;
+}
+
+interface EntityReference {
+  ref: string;                     // the only identifying field, see §5
+  label?: string;
+  role?: "primary" | "selected" | "related";
+}
+
+interface Observation {
+  key: string;                     // namespaced, see §6.1
+
+  presentedAs: {                   // what the user saw
+    value?: unknown;
+    unit?: string;
+    text?: string;
+  };
+
+  source?: "ui" | "api" | "derived";
+  observedAt?: string;             // when the reading was taken, see §7.3
+  resourceRef?: string;            // where to fetch the authoritative value
+}
+```
+
+### 4.1 `attention`
+
+MUST be present; MAY be empty. A view with no defined attention is legitimate; inventing one is not. Every `scopeId` referenced MUST exist in `scopes`.
+
+**Resolving `attention` is the producer's sole responsibility.** When several parts of an application contribute attention claims, the binding MUST merge them into the single ordered list **before serialisation**: the wire format never carries competing or unresolved claims, and a consumer never arbitrates. `attention[0]` expresses the producer's claim of primary salience — it is not a quantity comparable across producers. The merge mechanism is binding-specific and out of scope for the core.
+
+Absent an application-specific rule, a producer SHOULD rank targets whose `reason` is `manual` or `overlay` above `selection`, and `selection` above `active-view` and `route`. A claim SHOULD be a pure function of observed state: an arrival of data, a re-registration or a re-render MUST NOT change the order when the observed state has not changed.
+
+**Attention MUST NOT be derived from DOM or input focus.** Which control holds the caret is not what the user's words refer to — an assistant docked beside the page would otherwise steal the context the instant it is typed into. Attention follows route, selection, mode and overlay, which are state; focus is an event.
+
+### 4.2 `scopes`
+
+A **flat** list; hierarchy is expressed with `parentId`. A `parentId` MUST reference a scope present in the same snapshot.
+
+**Core invariant:** *an inactive scope never appears in a snapshot.* This replaces the v0.1 criterion "destroying a component removes its scope", which was only verifiable in component frameworks. "Active" means *presented according to state*: an unselected tab, an untriggered lazy block, a cached-but-hidden view and a collapsed section are all application state, and their scopes MUST be absent.
+
+**Identity is per instance, not per definition.** A scope `id` identifies one instance within this snapshot, not a component class or a template. A binding that instantiates one definition more than once — two panels side by side, a list of cards — MUST mint a distinct id per instance. Instance ids MUST be derived from the domain data that distinguishes the instances, and MUST NOT derive from mount order, counters, randomness or timestamps: those change across renders, and §7.1 requires a revision that only moves when content moves. `duplicate-scope-id` therefore remains an error, not a legitimate multi-instance case.
+
+**`parentId` expresses semantic ownership**, never render position. A scope rendered elsewhere in the document — a portal, a teleport, an overlay attached to the body — keeps the parent that semantically owns it.
+
+The **order of the `scopes` array carries no meaning**: a consumer MUST NOT infer salience from it. Salience lives only in `attention`.
+
+### 4.3 `state`
+
+Distinguishes three conditions that otherwise collapse into "empty scope": I am loading, I failed, there is nothing.
+
+`errorCode` MUST be a namespaced code — `vops.host.unreachable`, `vops.metrics.timeout` — and MUST NOT carry the error text: a free-form message coming from a backend is an injection vector. A scope carrying `errorCode` MUST also set `error: true`.
+
+The three flags are deliberately **not** mutually exclusive: a real UI keeps the previous content on screen while refreshing, and shows it again beside an error. Forcing exclusivity in the core would be stricter than reality. An application profile MAY raise `loading-and-error` or `loading-and-empty` as **warnings**; the core does not.
+
+### 4.4 `completeness`
+
+SHOULD be present on every scope representing a paginated, filtered or virtualised list. Without it, "restart the broken one" resolves against the rendered rows rather than against the set.
+
+### 4.5 `EntityReference`
+
+A single identifying field (`ref`). The v0.1 triple `ref` + `type` + `id` has been removed: two representations of one identity force every validator to define behaviour for the case where they disagree.
+
+### 4.6 `Observation`
+
+`presentedAs` is **required** and is the only container for the value: there is no bare `value` field beside it. One place where the datum lives, for the same reason as §4.5.
+
+Three rules make it honest:
+
+- `presentedAs` MUST carry `value` or `text`. A `unit` on its own presents nothing.
+- `value` MUST be a **compact scalar** — number, boolean, null or a short string. Charts, series, objects and API structures MUST live behind `resourceRef` (§9). A `null` value is legitimate: it is how a UI showing "—" says the reading was unavailable.
+- `text` MUST be accompanied by `source`, because free text is admitted only with provenance (§3.5).
+
+The meaning of an observation is always: *"the interface presented this, referring to that moment."* Never: *"this is true now."*
+
+### 4.7 Complete example
+
+```json
+{
+  "schemaVersion": "0.2",
+  "app": { "id": "vops", "version": "0.4.1" },
+  "surface": {
+    "id": "host-detail",
+    "route": "#host",
+    "revision": 42,
+    "generatedAt": "2026-08-05T16:09:41Z",
+    "locale": "en-GB"
+  },
+  "attention": [
+    { "scopeId": "host-live-status", "entityRef": "vops://host/vmi3399032", "reason": "route" }
+  ],
+  "scopes": [
+    {
+      "id": "host-detail",
+      "kind": "page",
+      "label": "Host detail",
+      "entities": [
+        { "ref": "vops://host/vmi3399032", "label": "vmi3399032", "role": "primary" }
+      ],
+      "observations": [
+        {
+          "key": "vops.host.provider",
+          "presentedAs": { "text": "contabo" },
+          "source": "api"
+        }
+      ]
+    },
+    {
+      "id": "host-live-status",
+      "parentId": "host-detail",
+      "kind": "region",
+      "label": "Live status",
+      "state": { "loading": false, "empty": false },
+      "observations": [
+        {
+          "key": "system.cpu.utilization",
+          "presentedAs": { "value": 92, "unit": "percent" },
+          "source": "api",
+          "observedAt": "2026-08-05T16:07:12Z",
+          "resourceRef": "vops://host/vmi3399032/metrics/cpu?window=1h"
+        },
+        {
+          "key": "vops.host.window",
+          "presentedAs": { "text": "1h" },
+          "source": "ui"
+        }
+      ],
+      "completeness": { "shown": 3, "total": 3 }
+    }
+  ]
+}
+```
+
+---
+
+## 5. Entity references
+
+### 5.1 Grammar
+
+```text
+<namespace>://<entity-type>/<entity-id>
+```
+
+Examples: `vops://host/vmi3399032`, `vops://server/srv_123`, `vops://app/nextcloud`.
+
+The entity-id is a **single percent-encoded segment**: it MUST NOT contain `/`, `?` or `#`. A composite identity uses a separator inside the segment — `vops://app/vmi3399032:nextcloud` — rather than a nested path, so that every reference parses the same way with no ambiguity about where the type ends and the identity begins.
+
+### 5.2 Requirements
+
+A `ref` MUST be stable over time, serializable, interpretable by the producer, and passed **explicitly** to operational tools.
+
+A `ref` MUST NOT be used as proof of authorisation (§8.1).
+
+A consumer MAY extract type and identifier from it, but MUST NOT construct an entity other than the one expressed.
+
+### 5.3 Obligation on the authoritative side
+
+A server receiving a `ref` in a tool call MUST still resolve it, validate it, apply the tenant, verify authorisation and revalidate current state. No tool MUST exist in the form "act on the current entity": the implicit state of a browser tab is not a parameter.
+
+---
+
+## 6. Vocabulary and namespacing
+
+This specification defines no universal ontology, and will not introduce one until several independent applications need to interoperate over the same terms. What it defines is a **grammar**, whose conformance cost is one regular expression.
+
+### 6.1 Observation keys
+
+Keys MUST be namespaced (at least one dot) or belong to a recognised vocabulary.
+
+```text
+system.cpu.utilization      ← recognised vocabulary (OpenTelemetry)
+system.memory.utilization
+vops.host.status
+vops.deployment.phase
+```
+
+For infrastructure metrics a producer SHOULD prefer names from the **OpenTelemetry Semantic Conventions** where applicable. This is an interoperability choice of the application profile, **not** a dependency of the core.
+
+### 6.2 Scope kinds — reserved values
+
+```text
+page   region   selection   list   form   overlay
+```
+
+Extensions MUST be namespaced: `vops.terminal`, `flui.canvas`.
+
+`overlay` covers dialogs and drawers: those are presentation words, and the core speaks of attention. A binding MAY distinguish them locally.
+
+### 6.3 Attention reasons — reserved values
+
+```text
+route   selection   active-view   overlay   manual
+```
+
+Namespaced extensions are allowed.
+
+### 6.4 No registry
+
+This version does **not** introduce a global registry, URI resolution, RDF, JSON-LD, or universal vocabulary governance. The consumer is a language model, not a reasoner: a vocabulary must be **readable**, not resolvable.
+
+---
+
+## 7. Revision, freshness and staleness
+
+### 7.1 Revision
+
+`surface.revision` MUST be a monotonically increasing integer for the lifetime of the Surface session. It changes when the content a snapshot would express changes.
+
+Revision does **not** replace backend versions, ETags or revisions: it diagnoses UI context, it does not protect a mutation.
+
+### 7.2 Revision on request and on response
+
+The host SHOULD record the revision in force when the message was sent, and carry it back on the response:
+
+```json
+{ "message": "Why is CPU high?", "surfaceRevision": 42, "surface": { } }
+{ "surfaceRevision": 42, "answer": "…" }
+```
+
+If the UI has since moved to revision 45, the client MAY show a "based on an earlier view" marker, avoid visually binding the answer to the new focus, or ask for a context refresh before an action. It MUST NOT automatically invalidate a historically correct answer.
+
+*Why this matters:* an agent that reasons for forty seconds answers about an entity the user has already left. Without this link, that answer is indistinguishable from a current one.
+
+### 7.3 `observedAt`
+
+`surface.generatedAt` is when the snapshot was produced. `observation.observedAt` is when the underlying value was measured or received. **They are not equivalent.**
+
+When `observedAt` is absent, a consumer MUST treat the age of the value as **unknown**. It MUST NOT assume it equals `generatedAt`: doing so would manufacture a freshness nobody measured.
+
+---
+
+## 8. Trust boundary, security and redaction
+
+### 8.1 The Surface is never trusted
+
+A Surface comes from the client and MAY be altered. It MUST NOT be trusted for authorisation, tenancy, permissions, risk level, approval, capability availability or current operational state.
+
+All of those MUST be revalidated server-side on every operation.
+
+### 8.2 Redaction before serialisation
+
+There is no `sensitivity` field: security MUST NOT depend on a label a consumer is free to ignore.
+
+> **Rule:** a value that must not leave the process building the snapshot MUST NOT be present in the snapshot.
+
+The producer MUST redact **before** serialisation. The following MUST NOT appear: tokens, passwords, sensitive environment variables, keys, authentication headers, whole logs, unnecessary personal data.
+
+### 8.3 Perimeter of this version
+
+v0.2 declares itself:
+
+```text
+first-party · same-origin · single application trust domain
+```
+
+It does **not** claim to solve third-party iframes, untrusted widgets, browser extensions, cross-origin composition, provider signing, or provenance attestation.
+
+The runtime MUST nevertheless prevent external code from registering scopes by default, absent an explicit integration.
+
+### 8.4 Host-side encapsulation (prompt injection)
+
+Resource names, logs, findings and any content originating from observed systems are **untrusted data**, even when the Surface itself was produced correctly.
+
+The assistant host MUST:
+
+1. wrap the snapshot in a block explicitly declared as untrusted data describing what the user is looking at;
+2. never present Surface content as instructions;
+3. truncate free text per §9;
+4. prefer codes, structured values and `resourceRef` over prose.
+
+It SHOULD further prefer a **compact, deterministic digest** of the snapshot in the prompt, exposing the full snapshot only on the model's explicit request through a tool — so the budget stays small and the full content arrives through the path the host already treats as tool output.
+
+---
+
+## 9. Budget and truncation
+
+The core MUST prevent a snapshot from becoming an arbitrary dump. No universal limit is frozen in this version: the default will be chosen from pilot measurements.
+
+A builder MUST support a configurable budget and expose its measurements:
+
+```ts
+createSurface(definitions, getState, {
+  maxBytes: 32_768,
+  maxScopes: 30,
+  maxObservationsPerScope: 20,
+  maxTextLength: 500,
+});
+```
+
+Measurements the builder MUST be able to report: JSON bytes, estimated tokens, number of scopes, observations and entity refs, fields truncated.
+
+When the budget is exceeded, the truncation order MUST be:
+
+1. free text first;
+2. then the least salient observations;
+3. **never** the entity references of the primary attention;
+4. `surface.truncated` becomes `true`;
+5. affected scopes expose `completeness.truncated`.
+
+The following MUST NOT be serialised under any circumstance: full charts, long lists, whole logs, raw API responses, store objects.
+
+---
+
+## 10. Runtime (not required for conformance)
+
+### 10.1 Core: pure definitions
+
+The model does **not** require component lifecycles. Its nucleus is a composition of pure definitions over application state:
+
+```ts
+interface SemanticScopeDefinition<S> {
+  id: string;
+  parentId?: string;
+  kind: string;
+  isActive(state: S): boolean;
+  read(state: S): ScopeContribution;   // entities, observations, state, completeness
+}
+
+function createSurface<S>(
+  definitions: SemanticScopeDefinition<S>[],
+  getState: () => S,
+  budget?: Budget,
+): { snapshot(): SurfaceSnapshot };
+```
+
+This works with a single store (Alpine and similar), page controllers, SSR, multi-page applications, and tests without a browser.
+
+*Note on multi-instance definitions:* the static `id` in this sketch is adequate only for definitions that produce one scope. A binding whose definitions instantiate more than once MUST mint an id per instance (§4.2) — copying this sketch literally is how a component binding builds itself an id collision. How instance keys are sourced (a React `key`, an Angular `trackBy`, a route parameter), how attention claims are merged, and whether the `scopes` array needs a canonical order are **binding concerns**, deliberately unspecified until a second, component-based implementation exists to exercise them.
+
+### 10.2 Dynamic registration: an optional adapter
+
+Component frameworks MAY add `register` / `invalidate` / `unregister` / `subscribe` on top of the core. These APIs belong to the binding, **not** to the wire format, and do not contribute to conformance.
+
+### 10.3 Lazy materialisation
+
+A runtime MUST NOT serialise continuously. It holds references to definitions, parent–child relations, activation state and a revision number, and builds a snapshot **only on request**.
+
+A snapshot MUST derive from a **single coherent read of state**, never be accumulated across ticks: otherwise it describes a moment that never existed. A contribution whose parent is absent from that read MUST be omitted rather than emitted as an orphan — a transiently invalid snapshot is worse than a smaller one. A snapshot taken while something is still mounting is legitimate, not a race: what has not been presented does not appear.
+
+---
+
+## 11. Transports
+
+The format is **transport-independent**. A conforming producer MAY deliver it over any of these channels without the model changing.
+
+### 11.1 Application request body
+
+The pilot's case: the snapshot travels in an **optional** field of the message to the assistant. The receiver MUST validate it against the schema and MUST discard it silently if invalid — a defect in the Surface MUST NOT fail the user's request (§12.1, item 9).
+
+### 11.2 MCP content block or resource
+
+A snapshot MAY be exposed as the result of a read-only tool, or as a resource, so a model can read it on request instead of always receiving it in the prompt.
+
+### 11.3 SSR and multi-page applications
+
+```html
+<script type="application/json" data-semantic-surface>
+  { "schemaVersion": "0.2", "...": "..." }
+</script>
+```
+
+A producer emitting **only** this tag is **fully conforming**. This is the test that keeps §10 honest: if a future version made this form impossible, the core would once again be contaminated by the API.
+
+### 11.4 Layout anchoring (optional binding)
+
+A web binding MAY mark the element rendering a scope:
+
+```html
+<section data-surface-scope="host-live-status"> … </section>
+```
+
+This attribute is not required, does not enter the wire format, carries no semantic data and does not replace the snapshot. It lets a host that has DOM and pixels compute bounding boxes **on demand**, instead of putting unstable coordinates — which change on every scroll — inside the snapshot.
+
+---
+
+## 12. Conformance
+
+### 12.1 Conforming producer
+
+A producer conforms when it:
+
+1. emits snapshots valid against the schema;
+2. uses a single canonical `ref` per entity, with the grammar of §5.1;
+3. namespaces observation keys and non-reserved scope kinds;
+4. never includes an inactive scope;
+5. distinguishes loading, error and empty;
+6. declares the incompleteness of lists it truncates or filters;
+7. redacts secrets **before** serialisation;
+8. respects the configured budget or declares truncation;
+9. **behaves identically when Surface production is disabled** — the Surface is never a prerequisite for the UI;
+10. does not copy state into a parallel structure (§3.4).
+
+### 12.2 Conforming consumer
+
+A consumer conforms when it:
+
+1. does not treat the Surface as authoritative for truth, permissions or availability (§8.1);
+2. uses explicit `ref` values in tool calls, never the implicit state of a view;
+3. treats the age of a value without `observedAt` as unknown;
+4. encapsulates the Surface as untrusted data (§8.4);
+5. revalidates data against the authoritative source before a diagnosis or an action.
+
+### 12.3 Two levels of validation
+
+JSON Schema cannot express several of the MUSTs in this specification: it validates one document's shape, and knows nothing about cross-references, history or producer behaviour. Validation is therefore defined at two levels, and an implementation MUST run both:
+
+```text
+validateSchema(snapshot)                        // structure
+validateSemantics(snapshot, previousSnapshot?)  // coherence
+```
+
+```ts
+interface SemanticValidationIssue {
+  code: string;
+  path: string;
+  message: string;
+  severity: "error" | "warning";
+}
+
+interface SemanticValidationOptions {
+  previousSnapshot?: SurfaceSnapshot;
+  maxBytes?: number;
+}
+
+function validateSurfaceSemantics(
+  snapshot: SurfaceSnapshot,
+  options?: SemanticValidationOptions,
+): SemanticValidationIssue[];
+```
+
+Minimum checks on a single snapshot:
+
+| Code | Severity |
+|---|---|
+| `duplicate-scope-id` | error |
+| `missing-attention-scope` — an `attention.scopeId` absent from `scopes` | error |
+| `missing-parent-scope` — a `parentId` absent from `scopes` | error |
+| `cyclic-scope-hierarchy` | error |
+| `duplicate-entity-ref` — the same `ref` twice in one scope | error |
+| `attention-entity-not-in-scope` — an `entityRef` not present in the scope it points at | warning |
+| `shown-exceeds-total` | error |
+| `inconsistent-truncation` — a truncated scope with `surface.truncated` unset | error |
+| `invalid-timestamp-value` — lexically valid but not a real instant | error |
+| `budget-exceeded` — requires `options.maxBytes` | error |
+
+Across snapshots, requiring `options.previousSnapshot`:
+
+| Code | Severity |
+|---|---|
+| `invalid-revision` — revision not strictly increasing | error |
+
+**On `invalid-timestamp-value`:** the schema's timestamp pattern constrains lexical shape and forces an explicit offset, but a well-formed impossible instant — `2026-99-45T29:81:75+84:92` — still satisfies it. Verifying that the instant exists belongs here. `Date.parse` alone is not sufficient: its behaviour on edge cases differs between runtimes, so an implementation SHOULD verify component ranges and round-trip the value, or use a strict ISO 8601 parser.
+
+### 12.3.1 Producer conformance — outside both validators
+
+Four obligations cannot be evidenced by any artefact, because they are properties of the code that produced it, not of the document. Naming them here with their own codes prevents a future implementer from trying to "solve" them in JSON Schema:
+
+| Code | Obligation |
+|---|---|
+| `inactive-scope-emitted` | an inactive scope never appears (§4.2) |
+| `secret-not-redacted` | redaction happens before serialisation (§8.2) |
+| `parallel-semantic-state` | no state structure parallel to the UI's (§3.4) |
+| `surface-disabled-changes-ui` | the UI behaves identically with Surface production off (§12.1, item 9) |
+
+These are verified by the suite of §12.4.
+
+*Implementation note:* JSON Schema validators silently ignore formats they do not know, so a validator SHOULD enable format validation (for Ajv: `ajv-formats`). Timestamps do not depend on it for their shape: they carry a regular-expression duplicate of the format and require an explicit offset, so a lexically malformed or ambiguous `generatedAt` is rejected even with formats disabled — an age computed from an ambiguous timestamp is worse than no age at all. Temporal validity is a separate matter, and belongs to `invalid-timestamp-value`.
+
+### 12.4 Conformance suite
+
+An implementation claims conformance by passing a suite that MUST include at least:
+
+- valid and invalid wire-format fixtures;
+- the ten semantic checks of §12.3, each with a failing case;
+- snapshots during loading, during an error, and over a truncated list;
+- absence of secrets in a case constructed to contain them;
+- entity reference de-duplication;
+- absence of inactive scopes;
+- behaviour with Surface production disabled.
+
+---
+
+## 13. Versioning and extensions
+
+### 13.1 Version
+
+`schemaVersion` is a **`major.minor` compatibility version**, not a full SemVer string: it names a compatibility family, so that non-breaking corrections to the schema can ship without invalidating snapshots already in the wild. It is independent of the vocabularies an application uses.
+
+`minor` increases when fields are added or constraints are relaxed. `major` increases when a field is removed or renamed, when a constraint is tightened, or when the meaning of an existing field changes — all of which can invalidate a conforming producer.
+
+### 13.2 Extensions
+
+The `extensions` field — on the snapshot and on every scope — accepts namespaced keys (`vops.*`, `flui.*`). A consumer MUST ignore extensions it does not know. Every other object in the wire format is closed: an unexpected field is a validation error, not an extension.
+
+### 13.3 Registered extensions
+
+**SS-ATTENTION** *(not implemented; shape pre-committed)* — an agent→UI channel limited to attention:
+
+```ts
+type AttentionTarget = { scopeId: string } | { entityRef: string };
+interface SurfaceIntent { kind: 'reveal' | 'highlight'; target: AttentionTarget; note?: string }
+requestAttention(intent: SurfaceIntent): 'applied' | 'declined' | 'unknown-target';
+```
+
+Constraints already decided, should it ever be adopted: it is a **request**, and the UI MAY refuse it (`declined` is a legitimate outcome, and it is the antidote to focus stealing); it never submits, never focuses an input, never triggers a fetch; **every future `kind` must be paraphrasable as "move or mark attention", never as "do"**. A general layer of persistent agent annotations rendered inside the product UI will never enter the model: content written by an agent and rendered in the product is a phishing primitive.
+
+### 13.4 Explicitly deferred
+
+Public standardisation; a universal vocabulary registry; JSON-LD or RDF; provider signing; cross-origin composition; a universal capability registry; a navigation model; funnel automation; form prefilling; click automation; persistent annotations; cross-device sharing; Surface persistence; `requestAttention`; full equivalence across web, CLI, TUI and voice; full automatic generation from Flui.
+
+---
+
+## 14. Decisions closed in this version
+
+Three questions were left open by the decision record. They are closed here; each is reversible in one line, and the rationale is recorded so a future revision does not have to reconstruct it.
+
+| # | Decision | Rationale |
+|---|---|---|
+| **1** | **`capabilityHints` are removed for good**, from the core and from the pilot | They live in the untrusted part of the system and duplicate an authoritative registry that already exists; an agent derives capabilities from entity type and intent. This is decided **on principle** (trust boundary), not pending a measurement: no experimental arm is planned to measure their uplift |
+| **2** | **No package is extracted until a second binding exists** | The decision record deferred the document split while creating two packages with a single consumer: the same premature generalisation, applied to code. The implementation lives inside the pilot application; the JSON Schema is published as a versioned file from day one |
+| **3** | **Bare `Observation.value` removed**: only `presentedAs` exists | Two fields for one truth is the same defect as the `ref`/`type`/`id` triple removed in this version. A producer would fill both, inconsistently |
+
+One addition introduced here and absent from the earlier documents: the **`extensions`** field (§13.2), needed so that closing the wire-format objects does not make application extensions impossible.
+
+### 14.1 Schema hardening
+
+A review of the first schema draft found four constraints that were stated in prose but not enforced, and one inconsistency. All are now closed in both documents:
+
+| Finding | Resolution |
+|---|---|
+| `presentedAs` accepted `{ "unit": "percent" }` — a unit presenting nothing | `value` or `text` is now required (§4.6) |
+| `value` accepted arbitrarily large objects and strings; only arrays of 32+ items were blocked | `value` is a compact scalar; structures live behind `resourceRef` (§4.6) |
+| Free text was admitted "with provenance", but `source` was optional | `source` is required whenever `text` is present (§4.6) |
+| `errorCode` accepted a full sentence, contradicting its own description | `errorCode` is a namespaced code and implies `error: true` (§4.3) |
+| `schemaVersion: "0.2"` was declared SemVer, which would be `0.2.0` | It is a `major.minor` compatibility version (§13.1) |
+| `entityRef` claimed percent-encoding but accepted `%ZZ` and a trailing `%` | The pattern now admits only unreserved and sub-delimiter characters or valid `%XX` octets (§5.1) |
+| The timestamp pattern was described as rejecting any malformed value, while it constrains lexical shape only | The claim is narrowed, and temporal validity becomes `invalid-timestamp-value` in the semantic validator (§12.3) |
+
+### 14.2 Composition and attention (clarification pass)
+
+A page is normally made of components, each declaring its own semantic fragment; someone must then **merge** those fragments and **decide which one holds attention**. The v0.2 wire format already answers the first question by construction — `scopes` is a flat array with `parentId`, so merging is concatenation rather than tree surgery — but it answered the second only by saying the list is "ordered by salience", without ever saying who orders it.
+
+Leaving that unsaid was the real gap, and it is closed here **without adding a mechanism**: the pilot has one store and no components, so any arbitration algorithm would be designed against no case that could falsify it. What is added is the assignment of responsibility (§4.1), the rule that identity is per instance (§4.2), the fact that `parentId` is semantic rather than positional (§4.2), and the atomicity of a snapshot (§10.3) — each a consequence of rules the specification already contained. The default ranking of reasons is a SHOULD, and it is admissible only because vops genuinely exercises it: route, selection and overlay do compete on the same page.
+
+The arbitration mechanism itself, instance keying, ownership and any canonical ordering of `scopes` wait for the second, component-based binding. A.9 now names them among the things the pilot does not prove.
+
+Two further clarifications came from asking what happens when an assistant is docked beside the page: **attention is never DOM focus** (§4.1) and **a Surface-observing UI contributes no scopes** (§2.4). Both were already implied — a claim is a function of state, and an inspector is not part of the product — but an implementer holding `document.activeElement` would have made the obvious mistake, and the assistant would have stolen the context the moment it was used.
+
+Neither the wire format nor the schema changed in this pass, so `schemaVersion` remains `0.2`.
+
+### 14.3 Boundary of the schema
+
+The schema review established the boundary of §12.3: a JSON Schema validates one document's shape and cannot see cross-references, history or producer behaviour. That is not a defect of the schema — it is the reason the semantic validator exists as a named, separate level rather than as an unstated expectation.
+
+---
+
+## Annex A — vops pilot *(informative)*
+
+This annex is application-specific and translates the model onto the product's real objects. It does not contribute to conformance.
+
+### A.1 Page
+
+The pilot page is the **Host detail** view of vops, the sponsoring product. Its markup, its view state and its page logic live in that product's source tree, not in this repository, so nothing in this annex can be opened from here: it is recorded because a binding that was actually built is the only evidence a model of this kind survives contact with a real screen.
+
+Correction relative to the earlier documents, verified against the code: there is **no "Server Details" page**; there is **no "active tab"** — the segmented control is a **time window** (`mon.range`, shared with the Monitoring page) — and there is **no "selected deployment"** on that page: installed apps live in a different view.
+
+### A.2 Pilot scopes
+
+| Scope | kind | Content |
+|---|---|---|
+| `host-detail` | `page` | primary host entity, provider, presented address, connection state |
+| `host-live-status` | `region` | presented cpu/ram/disk with `observedAt`, active time window, `resourceRef` to the full series, `state` |
+| `host-checks` | `list` | count and worst severity of findings, `completeness`; **never** the full texts |
+| selection | `selection` | the opened finding, when one exists |
+
+### A.3 Not to be exposed
+
+Capability hints; permissions; risk level; approval policy; full metric series; whole logs; full finding texts; secrets; summaries invented for the model.
+
+### A.4 Data path
+
+1. the UI builds the snapshot from pure definitions over existing state;
+2. the message to the assistant carries the **user's plain text** plus `surface` and `surfaceRevision` — the current `"About X:"` text prefix is retired, because it pollutes the stored conversation history;
+3. the receiver validates against the schema, applies the cap, and silently discards an invalid snapshot;
+4. towards the model: a **compact deterministic digest** in the prompt, encapsulated as untrusted data, plus a **read-only tool** returning the full snapshot on request;
+5. only `{ surfaceId, revision, route, entityRefs }` is persisted to the audit trail — never the full snapshot.
+
+### A.5 Positive questions
+
+1. "Which host am I looking at?"
+2. "How is it doing?"
+3. "Why is this CPU high?"
+4. "Show me the top consuming processes."
+5. "What does this check say?"
+6. "Restart this host."
+
+### A.6 Negative controls
+
+1. a question about a host that is not visible MUST NOT be resolved against the current host;
+2. a view with no selection MUST NOT produce an invented selection;
+3. a stale value MUST NOT be presented as current state without verification;
+4. hostile text inside findings — which arrive from the remote machine over SSH — MUST NOT become an instruction: the test is run by seeding real hostile strings on the staging box;
+5. an unavailable capability MUST NOT be inferred from the UI;
+6. changing page during reasoning MUST produce an answer markable as based on an earlier view.
+
+### A.7 Measurement
+
+Two arms, holding model, system prompt, tools, authorisations, dataset and maximum turn count constant:
+
+```text
+A. assistant + authoritative tools, no Semantic Surface
+B. assistant + authoritative tools, with Semantic Surface
+```
+
+Metrics, all from machine artefacts rather than a model judge: correct entity-ref resolution; first tool call carrying the correct identifier; number of calls before correct grounding; clarification requests; precision of the first capability chosen; deictic errors; bytes and tokens added; answers based on stale data; hostile-string containment; false associations on the negative questions.
+
+**Thresholds MUST be fixed before the run.**
+
+### A.8 Pilot acceptance criteria
+
+1. the Surface validates against the schema;
+2. the assistant identifies the current host without the user naming it;
+3. changing selection changes the entity ref;
+4. an inactive scope never appears in the snapshot;
+5. loading, error and empty are distinguishable;
+6. a truncated list declares its incompleteness;
+7. no secret appears in the snapshot;
+8. no capability hints are present;
+9. mutations use explicit `ref` values in tool calls;
+10. the authoritative side revalidates authorisation, state and approval;
+11. the snapshot stays within budget or declares truncation;
+12. the answer retains its originating revision;
+13. the UI behaves identically with the Surface disabled;
+14. arm B clears the uplift thresholds fixed before the test.
+
+### A.9 What the pilot does NOT prove
+
+| Particularity | Hypothesis left unverified | Second case required |
+|---|---|---|
+| No component lifecycle | register/unregister, cleanup, ownership, **arbitration of attention between competing components**, instance keying, whether `scopes` needs a canonical order | a component binding (Angular/Flui) |
+| Assistant is a one-shot external process | mid-conversation context refresh | a persistent in-browser assistant |
+| Pre-existing, strong governance | whether the Surface degrades security where tools are bare wrappers | an application with no action broker |
+| Single user, local, one trust domain | §8.3, cross-tenant, staleness from concurrent actors | a multi-tenant application |
+| Small surface, depth 2 | de-duplication, revision churn, performance | a page with dozens of scopes |
+
+Claim permitted on success:
+
+> The Semantic Surface improves contextual grounding for an assistant with authoritative tools on one single-page UI.
+
+Claims **not** permitted: universal portability; cross-origin security; effectiveness on every framework; effectiveness on CLI, TUI or voice; suitability as a web standard; general cost reduction.
+
+---
+
+## Annex B — Positioning and prior art *(informative)*
+
+| Item | Relationship to the Semantic Surface |
+|---|---|
+| **WebMCP** (W3C Web Machine Learning CG) | Standardises tool registration by the page (`document.modelContext.registerTool`, JS functions or `<form>` elements); **observed state is explicitly out of scope**. An early proposal, not a standard, without widespread implementation. It is the natural complement: the Surface is the context side of that action side. No dependency is created |
+| **MCP** | The authoritative operational channel. It provides fresh data, capabilities, guardrails and execution; the Surface provides attention, references and presentation. `resourceRef` points naturally at its resources |
+| **Accessibility tree / ARIA** | The closest existing thing, and not enough: per-widget, without domain entities, without salience, without freshness, and far more expensive in tokens. From it comes the lesson behind §11.4: declarative binding in the markup is what survives |
+| **schema.org / JSON-LD** | From it comes the profile mechanism — adopted in minimal form in §6 — and the adoption lesson: a standard takes hold when an important consumer reads it and returns value. It does not cover the Surface: it describes published documents, not the runtime state of a view |
+| **W3C Web of Things — Thing Description** | A close structural parallel: properties ≈ observations, actions ≈ capabilities, plus *events*, which are absent here and remain a future candidate |
+| **OpenTelemetry Semantic Conventions** | Vocabulary reused for metrics (§6.1), and a governance model worth imitating |
+
+### A note on adoption
+
+This version has **one consumer, and it is the first party**. That is stated deliberately: it guards against over-designing for adopters who do not yet exist, and it keeps every portability claim honest until a second implementation — preferably SSR, the hardest test — has demonstrated it.
+
+---
+
+## Provenance
+
+| Document | Role |
+|---|---|
+| `vops-semantic-surface-spec.md` | v0.1, historical (Italian) — internal, not distributed |
+| `semantic-surface-v0.1-review.md` | technical review, 24 recommendations, historical (Italian) — internal, not distributed |
+| `semantic-surface-response-to-review-v0.2.md` | decision record, historical (Italian) |
+| **`semantic-surface-core-v0.2.md`** | **current specification** |
+| `semantic-surface.schema.json` | current validation schema |