@flui-cloud/semantic-surface 0.1.0

package/docs/agent-surface/semantic-surface-response-to-review-v0.2.md

@@ -0,0 +1,1122 @@
+# Semantic Surface — risposta alla revisione tecnica della v0.1
+
+**Documento di risposta a:** `Semantic Surface — revisione tecnica della v0.1`  
+**Documento originario:** `vops-semantic-surface-spec.md`  
+**Data:** 2026-08-05  
+**Stato:** Decision record per la preparazione della v0.2  
+**Obiettivo:** incorporare le osservazioni che migliorano il modello senza trasformare prematuramente il pilot vops in un programma completo di standardizzazione.
+
+---
+
+## 1. Verdetto generale
+
+La revisione tecnica coglie diversi problemi reali della v0.1 e migliora il progetto soprattutto in quattro punti:
+
+1. chiarisce che il contratto portabile è il **wire format**, non l’interfaccia TypeScript;
+2. impedisce alla Semantic Surface di diventare una copia dello store o del backend;
+3. separa meglio ciò che è stato presentato all’utente dalla fonte autorevole dei dati;
+4. mette in discussione correttamente la duplicazione delle capability nella UI.
+
+Il nucleo architetturale originario resta però valido:
+
+```text
+Semantic Surface
+        │
+        │ descrive il contesto della UI
+        ▼
+Assistant / Planner
+        │
+        │ interpreta l’intento e sceglie uno strumento
+        ▼
+MCP Server
+        │
+        │ autorizza, approva, valida ed esegue
+        ▼
+Application Services / Infrastructure
+```
+
+La revisione non richiede quindi di cambiare direzione. Richiede di **ridurre il core**, precisarne il significato e distinguere meglio:
+
+- modello;
+- trasporto;
+- implementazione runtime;
+- binding per framework;
+- integrazione specifica di vops.
+
+La v0.2 non sarà ancora presentata come standard universale. Sarà:
+
+> un modello portabile, con wire format esplicito, validato attraverso un pilot reale su vops.
+
+L’eventuale standardizzazione viene dopo che il modello ha prodotto valore misurabile e almeno una seconda implementazione ne ha dimostrato la portabilità.
+
+---
+
+## 2. Definizione aggiornata
+
+La definizione della v0.1 era:
+
+> La Semantic Surface descrive ciò che l’utente sta osservando.
+
+È corretta ma troppo ampia. Può indurre a includere nella Surface tutto ciò che appare nella pagina, fino a creare un duplicato semantico dell’applicazione.
+
+La definizione adottata per la v0.2 è:
+
+> **La Semantic Surface è una rappresentazione serializzabile e indipendente dal trasporto dell’attenzione corrente dell’utente e di ciò che l’interfaccia gli ha effettivamente presentato.**
+
+La Surface può descrivere:
+
+- route o vista corrente;
+- scope attivi;
+- entità primaria;
+- selezioni;
+- focus o attenzione;
+- tab, filtri e modalità attive;
+- overlay aperti;
+- stato di caricamento, errore o assenza di risultati;
+- valori effettivamente presentati;
+- timestamp dei dati presentati;
+- riferimenti con cui recuperare dati autorevoli.
+
+La Surface non deve diventare:
+
+- una replica dello store;
+- un dump delle risposte REST;
+- un modello completo del dominio;
+- un catalogo autorevole delle capability;
+- un sistema di autorizzazione;
+- una rappresentazione dei click;
+- un motore di browser automation.
+
+---
+
+## 3. Principio di ammissione dei dati
+
+La revisione propone una regola molto rigida:
+
+> entra nella Surface solo ciò che è vero unicamente nel client.
+
+La direzione è corretta, ma la formulazione è troppo restrittiva.
+
+Un valore recuperato dal backend può essere legittimamente incluso quando è stato realmente presentato all’utente. La sua presenza nella Surface non afferma che sia ancora autorevole; afferma che l’utente lo ha visto in quella forma e in quel momento.
+
+### Regola adottata
+
+Un’informazione può entrare nella Surface quando soddisfa almeno uno di questi criteri:
+
+1. esiste soltanto nella sessione UI, come selezione, focus, filtro o overlay;
+2. descrive il modo in cui un dato è stato presentato all’utente;
+3. è necessaria per risolvere una deissi come «questo server» o «quello selezionato»;
+4. indica lo stato semantico della vista, come loading, errore, empty state o troncamento;
+5. contiene un riferimento per recuperare dalla fonte autorevole i dati completi o aggiornati.
+
+Un’informazione non deve entrare quando:
+
+- è recuperabile in modo migliore e non ambiguo tramite un normale tool MCP;
+- non è rilevante per la vista o per l’attenzione corrente;
+- duplica grandi strutture del backend;
+- contiene segreti o dati non necessari;
+- è stata prodotta esclusivamente per “spiegare meglio” la pagina al modello senza essere parte del prodotto.
+
+### Esempio
+
+Corretto:
+
+```json
+{
+  "key": "system.cpu.utilization",
+  "observedAt": "2026-08-05T16:09:40Z",
+  "presentedAs": {
+    "value": 92,
+    "unit": "percent"
+  },
+  "resourceRef": "vops://server/srv_123/metrics/cpu"
+}
+```
+
+Il significato è:
+
+> L’interfaccia ha presentato all’utente un utilizzo CPU del 92%, riferito a quella rilevazione.
+
+Non significa:
+
+> La CPU è ancora autorevolmente al 92%.
+
+L’agente può usare `resourceRef` o una capability MCP per aggiornare il dato prima di formulare una diagnosi o proporre un’azione.
+
+---
+
+## 4. La regola anti-deriva
+
+Viene accolta integralmente la raccomandazione secondo cui il provider semantico deve leggere la stessa reactive state usata dalla UI.
+
+Non devono esistere due strutture indipendenti:
+
+```text
+UI state
+Semantic state
+```
+
+da sincronizzare manualmente.
+
+Il modello corretto è:
+
+```text
+Application state
+      │
+      ├── rendering UI
+      └── materializzazione Surface
+```
+
+Esempio:
+
+```ts
+const definitions = [
+  {
+    id: "server-details",
+    kind: "page",
+
+    isActive: state =>
+      state.section === "server-details",
+
+    read: state => ({
+      entities: state.selectedServer
+        ? [{
+            ref: `vops://server/${state.selectedServer.id}`,
+            label: state.selectedServer.name,
+            role: "primary"
+          }]
+        : [],
+
+      state: {
+        loading: state.serverLoading,
+        error: Boolean(state.serverError),
+        empty: !state.serverLoading && !state.selectedServer
+      }
+    })
+  }
+];
+```
+
+Questa regola riduce il rischio di divergenza tra ciò che vede l’utente e ciò che riceve l’agente.
+
+Non elimina gli errori di copertura: una pagina potrebbe non avere alcuna definizione semantica. La copertura può però essere controllata tramite:
+
+- inspector;
+- test;
+- lint sulle route principali;
+- criteri di accettazione del pilot.
+
+---
+
+## 5. Decisioni sulle raccomandazioni R1–R24
+
+### Legenda
+
+- **Accolta:** entra nella v0.2.
+- **Modificata:** il principio è valido, ma la proposta viene semplificata o limitata.
+- **Rinviata:** interessante, ma non necessaria per il pilot.
+- **Respinta:** introduce rigidità o complessità non giustificata.
+
+| Raccomandazione | Decisione | Motivazione |
+|---|---|---|
+| **R1 — quattro documenti separati** | **Modificata** | È corretta la separazione concettuale tra core, runtime, binding e authoring. Per ora produrremo un core, uno JSON Schema e un documento pilot. Lo split completo avverrà dopo una seconda implementazione. |
+| **R2 — conformità possibile senza runtime JS** | **Accolta** | Il modello normativo deve essere il wire format. SSR o MPA devono poter emettere uno snapshot valido senza implementare `register/unregister`. |
+| **R3 — solo dati unicamente client-side** | **Modificata** | Ammessi anche dati backend realmente presentati, purché identificati come presentazione stantia e accompagnati da provenienza temporale o `resourceRef`. |
+| **R4 — leggere la stessa reactive state** | **Accolta** | È una delle regole principali della v0.2. Vietata la copia parallela dello stato solo per l’agente. |
+| **R5 — vietare tutte le summary naturali** | **Modificata** | Vietate sintesi inventate ad hoc dalla UI per il modello. Ammessi testi realmente mostrati all’utente o prodotti dal backend, con limiti e provenienza. |
+| **R6 — un solo ref canonico** | **Accolta** | Elimina incoerenze tra `ref`, `type` e `id`. |
+| **R7 — focus multiplo ordinato** | **Accolta** | Necessario per split view, confronti e multi-selezione. Il nome adottato sarà `attention`. |
+| **R8 — stato dello scope** | **Accolta** | Loading, errore ed empty state sono necessari per interpretare correttamente una vista. |
+| **R9 — completezza delle liste** | **Accolta** | Importante per liste paginate, filtrate o virtualizzate. Resta opzionale quando non pertinente. |
+| **R10 — kind estensibile e namespaced** | **Modificata** | Il core definisce pochi valori raccomandati; sono ammesse estensioni namespaced. Non imponiamo subito una tassonomia completa. |
+| **R11 — eliminare dialog/drawer** | **Rinviata** | Per il core useremo il termine più neutro `overlay`. I binding possono distinguere dialog e drawer localmente. Non serve una migrazione complessa nel pilot. |
+| **R12 — Observation namespaced, source e budget** | **Modificata** | Namespacing e budget sì. `source` è utile ma opzionale. `observedAt` non viene automaticamente equiparato a `generatedAt`: sono momenti semanticamente diversi. |
+| **R13 — sensitivity inefficace** | **Accolta** | `sensitivity` viene rimossa dal wire format iniziale. I dati non esportabili devono essere redatti prima dello snapshot. |
+| **R14 — app, locale e profiles** | **Modificata** | `app.id`, `app.version` e `locale` entrano. `profiles` resta opzionale e sperimentale finché non esistono più vocabolari reali. |
+| **R15 — relation fuori dal core** | **Accolta** | Le relazioni di dominio sono normalmente meglio fornite dal backend. Potranno essere reintrodotte come estensione se il pilot dimostrerà un caso necessario. |
+| **R16 — budget normativo di 32 KB** | **Modificata** | È necessario un budget, ma 32 KB non viene congelato come limite universale. Il pilot userà warning, troncamento dichiarato e metriche reali. |
+| **R17 — grammatica, core vocabulary e profiles** | **Modificata** | Adottiamo namespace leggibili. Non introduciamo ancora URI risolvibili, registry o un sistema simile a JSON-LD. |
+| **R18 — OpenTelemetry obbligatorio** | **Modificata** | Riutilizzare OTel dove naturale, specialmente per metriche infrastrutturali, senza renderlo una dipendenza obbligatoria dell’intero modello. |
+| **R19 — companion di WebMCP** | **Accolta come posizionamento** | La Surface descrive contesto e attenzione; WebMCP e MCP descrivono o implementano azioni. Non leghiamo però il core all’evoluzione di WebMCP. |
+| **R20 — hint riferiscono tool, nessun canale proprietario** | **Accolta in forma più netta** | I `capabilityHints` escono dal core e dal primo pilot. La Surface non suggerisce tool; MCP resta il catalogo autorevole. Il formato resta indipendente dal trasporto. |
+| **R21 — definizione di multimodalità** | **Modificata** | La v0.2 non norma “la multimodalità” in senso ampio. Dichiara solo di essere indipendente dal mezzo e combinabile con pixel, DOM, voce o TUI da parte dell’host. |
+| **R22 — data attribute per ancoraggio DOM** | **Accolta come binding opzionale** | `data-surface-scope` è utile per collegare scope e layout, ma non entra nel wire format né nel core. |
+| **R23 — requestAttention** | **Rinviata** | È una buona estensione, ma introduce un canale agente→UI distinto dalla Surface descrittiva. Verrà valutata dopo il pilot come modulo separato. |
+| **R24 — definizione con reveal/highlight** | **Modificata** | Manteniamo la definizione canonica descrittiva. Non promettiamo ancora che l’agente possa dirigere l’attenzione. |
+
+---
+
+## 6. Capability: decisione aggiornata
+
+La v0.1 prevedeva `capabilityHints` nella Surface.
+
+Questa scelta viene abbandonata nel core e nel primo pilot.
+
+### Motivi
+
+1. vops possiede già un registry autorevole lato MCP;
+2. gli hint nel browser duplicano informazioni;
+3. possono divergere dal registry;
+4. possono orientare il planner verso operazioni non pertinenti;
+5. la Surface deve restare descrittiva;
+6. l’agente può derivare le capability dal tipo di entità e dall’intento.
+
+Il flusso diventa:
+
+```text
+Surface
+  └── attention: vops://server/srv_123
+              │
+              ▼
+Assistant interpreta l’intento
+              │
+              ▼
+MCP tools / capability resolver
+              │
+              ▼
+permessi + rischio + approvazione + stato
+```
+
+### Resolver opzionale
+
+Se il numero di strumenti diventerà elevato, il server MCP potrà esporre una capability read-only:
+
+```text
+vops_capabilities_resolve
+```
+
+Input:
+
+```json
+{
+  "entities": [
+    "vops://server/srv_123"
+  ],
+  "intent": "restart"
+}
+```
+
+Output:
+
+```json
+{
+  "capabilities": [
+    {
+      "id": "server.restart",
+      "tool": "server_restart",
+      "available": true,
+      "risk": "high",
+      "approval": "required"
+    }
+  ]
+}
+```
+
+Questo resolver non è parte della Semantic Surface. È parte del modello operativo MCP di vops.
+
+---
+
+## 7. Wire format proposto per la v0.2
+
+Il core viene espresso come JSON serializzabile. Le interfacce TypeScript sono soltanto una rappresentazione di sviluppo.
+
+```ts
+interface SurfaceSnapshot {
+  schemaVersion: "0.2";
+
+  app: {
+    id: string;
+    version?: string;
+  };
+
+  surface: {
+    id: string;
+    route?: string;
+    revision: number;
+    generatedAt: string;
+    locale?: string;
+    truncated?: boolean;
+  };
+
+  attention: AttentionTarget[];
+  scopes: SemanticScopeSnapshot[];
+}
+
+interface AttentionTarget {
+  scopeId: string;
+  entityRef?: string;
+  reason?: string;
+}
+
+interface SemanticScopeSnapshot {
+  id: string;
+  parentId?: string;
+  kind: string;
+  label?: string;
+
+  entities?: EntityReference[];
+  observations?: Observation[];
+
+  state?: {
+    loading?: boolean;
+    error?: boolean;
+    errorCode?: string;
+    empty?: boolean;
+  };
+
+  completeness?: {
+    shown: number;
+    total?: number;
+    filtered?: boolean;
+    truncated?: boolean;
+  };
+}
+
+interface EntityReference {
+  ref: string;
+  label?: string;
+  role?: "primary" | "selected" | "related";
+}
+
+interface Observation {
+  key: string;
+  value?: unknown;
+
+  presentedAs?: {
+    value?: unknown;
+    unit?: string;
+    text?: string;
+  };
+
+  source?: "ui" | "api" | "derived";
+  observedAt?: string;
+  resourceRef?: string;
+}
+```
+
+### Nota su `observedAt`
+
+`surface.generatedAt` indica quando è stato prodotto lo snapshot.
+
+`observation.observedAt` indica quando il dato rappresentato è stato rilevato o ricevuto.
+
+Non sono equivalenti.
+
+Quando `observedAt` è assente, il consumer deve considerare non nota l’età del dato. Non deve assumere automaticamente che coincida con `generatedAt`.
+
+---
+
+## 8. Formato dei riferimenti
+
+La v0.2 usa un solo campo canonico:
+
+```json
+{
+  "ref": "vops://server/srv_123"
+}
+```
+
+Il riferimento deve essere:
+
+- stabile;
+- serializzabile;
+- interpretabile dal produttore;
+- trasmesso esplicitamente ai tool;
+- non utilizzato come prova di autorizzazione.
+
+### Formato raccomandato
+
+```text
+<namespace>://<entity-type>/<entity-id>
+```
+
+Esempi:
+
+```text
+vops://server/srv_123
+vops://deployment/dep_44
+vops://database/db_19
+```
+
+Il consumer può estrarre tipo e ID, ma non deve inventare un’entità differente da quella espressa dal riferimento.
+
+Il server MCP deve comunque:
+
+- risolvere il riferimento;
+- validarlo;
+- applicare il tenant;
+- verificare autorizzazioni;
+- rivalidare lo stato corrente.
+
+---
+
+## 9. Vocabolario e namespacing
+
+La revisione ha ragione nel segnalare che stringhe completamente libere creano collisioni e ambiguità.
+
+La v0.2 adotta una regola minima, senza introdurre un’ontologia universale.
+
+### Observation key
+
+Le chiavi applicative devono essere namespaced oppure appartenere a un vocabolario riconosciuto.
+
+Esempi:
+
+```text
+system.cpu.utilization
+system.memory.utilization
+vops.server.status
+vops.deployment.phase
+```
+
+### Scope kind
+
+Il core raccomanda:
+
+```text
+page
+region
+selection
+list
+form
+overlay
+```
+
+Sono consentite estensioni:
+
+```text
+vops.terminal
+flui.canvas
+```
+
+### Nessun registry centrale
+
+La v0.2 non introduce:
+
+- un registry globale;
+- risoluzione di URI;
+- RDF;
+- JSON-LD;
+- una governance universale dell’ontologia.
+
+Questi problemi diventano reali solo quando più applicazioni indipendenti devono interoperare sugli stessi termini.
+
+### OpenTelemetry
+
+Per metriche infrastrutturali vops dovrebbe preferire, quando applicabile, i nomi già usati nelle OpenTelemetry Semantic Conventions.
+
+Questa è una scelta di interoperabilità del profilo vops, non una dipendenza obbligatoria del core Semantic Surface.
+
+---
+
+## 10. Runtime: core puro e binding opzionali
+
+La revisione dimostra correttamente che `register/unregister` non può essere il cuore del modello.
+
+Il runtime iniziale di vops può essere una composizione di definizioni pure:
+
+```ts
+interface SemanticScopeDefinition<S> {
+  id: string;
+  parentId?: string;
+  kind: string;
+
+  isActive(state: S): boolean;
+  read(state: S): ScopeContribution;
+}
+
+function createSurface<S>(
+  definitions: SemanticScopeDefinition<S>[],
+  getState: () => S
+): {
+  snapshot(): SurfaceSnapshot;
+}
+```
+
+Questo modello funziona per:
+
+- Alpine con store unico;
+- controller di pagina;
+- SSR;
+- applicazioni multi-page;
+- test senza browser.
+
+### Registrazione dinamica
+
+Framework a componenti come Angular o React possono aggiungere un adapter:
+
+```text
+register
+invalidate
+unregister
+subscribe
+```
+
+Queste API appartengono al binding runtime, non al wire format e non sono obbligatorie per la conformità del modello.
+
+### Invariante portabile
+
+Il criterio originario:
+
+> la distruzione di un componente rimuove lo scope
+
+viene sostituito da:
+
+> **uno scope inattivo non compare mai nello snapshot.**
+
+Questo vale in ogni ambiente, indipendentemente dal lifecycle del framework.
+
+---
+
+## 11. Testi liberi e prompt injection
+
+Non vengono vietati in assoluto i testi naturali.
+
+Vengono distinti tre casi.
+
+### Ammesso
+
+Testo realmente presentato all’utente:
+
+```json
+{
+  "key": "vops.deployment.error",
+  "presentedAs": {
+    "text": "Health check timed out"
+  },
+  "source": "api"
+}
+```
+
+### Ammesso con cautela
+
+Sintesi prodotta dal backend come parte del prodotto, testata e mostrata anche all’utente.
+
+### Vietato nel core
+
+Testo generato appositamente dal provider semantico per orientare il modello:
+
+```text
+Questo server sembra in grave difficoltà e dovrebbe essere riavviato.
+```
+
+### Regole
+
+- limiti di lunghezza;
+- nessun HTML arbitrario;
+- nessun segreto;
+- nessuna istruzione operativa;
+- incapsulamento dello snapshot come dato non attendibile;
+- preferenza per codici, valori strutturati e `resourceRef`;
+- sanitizzazione a cura dell’host dell’assistente.
+
+---
+
+## 12. Redazione e sicurezza
+
+Il campo `sensitivity` viene rimosso dal wire format iniziale.
+
+La sicurezza non può dipendere da un’etichetta che il consumer potrebbe ignorare.
+
+### Regola
+
+Un dato che non deve lasciare il processo della UI:
+
+> non deve essere presente nello snapshot.
+
+Il produttore deve applicare una redazione prima della serializzazione.
+
+### Perimetro iniziale
+
+Il pilot vops viene dichiarato:
+
+```text
+first-party
+same-origin
+single application trust domain
+```
+
+Non dichiara ancora di risolvere:
+
+- iframe di terze parti;
+- widget non attendibili;
+- estensioni browser;
+- composizione cross-origin;
+- firme dei provider;
+- attestazione di provenienza.
+
+Il runtime deve comunque impedire per default che codice esterno registri scope senza una integrazione esplicita.
+
+### Trust boundary
+
+La Surface non è mai attendibile per:
+
+- autorizzazione;
+- tenant;
+- permessi;
+- rischio;
+- approvazione;
+- disponibilità di una capability;
+- stato operativo corrente.
+
+Tali elementi vengono sempre rivalidati lato MCP/backend.
+
+---
+
+## 13. Budget e troncamento
+
+Il core deve impedire che lo snapshot diventi un dump arbitrario.
+
+Non viene però fissato immediatamente un limite universale di 32 KB.
+
+### Pilot vops
+
+Il builder deve misurare:
+
+- byte JSON;
+- token stimati;
+- numero di scope;
+- numero di observation;
+- numero di entity ref;
+- campi troncati.
+
+Deve supportare un budget configurabile.
+
+Esempio:
+
+```ts
+createSurface(definitions, getState, {
+  maxBytes: 32_768,
+  maxScopes: 30,
+  maxObservationsPerScope: 20,
+  maxTextLength: 500
+});
+```
+
+Se il budget viene superato:
+
+1. vengono troncati prima i testi;
+2. poi le observation meno salienti;
+3. non vengono mai eliminate le entity ref dell’attenzione primaria;
+4. `surface.truncated` diventa `true`;
+5. gli scope interessati espongono `completeness.truncated`.
+
+Il valore predefinito definitivo verrà scelto sulla base delle misure del pilot.
+
+---
+
+## 14. Revision e risposte stantie
+
+Ogni snapshot ha una `revision`.
+
+Quando l’utente invia un messaggio, l’host registra la revisione usata.
+
+```json
+{
+  "message": "Perché la CPU è alta?",
+  "surfaceRevision": 42,
+  "surface": {}
+}
+```
+
+La risposta dell’assistente deve essere associata alla stessa revisione:
+
+```json
+{
+  "surfaceRevision": 42,
+  "answer": "..."
+}
+```
+
+Se nel frattempo la UI è passata alla revisione 45, il client può:
+
+- mostrare un indicatore “basato sulla vista precedente”;
+- evitare di associare visivamente la risposta al nuovo focus;
+- chiedere un refresh del contesto prima di un’azione;
+- non invalidare automaticamente una risposta storica corretta.
+
+La revisione della Surface non sostituisce revisioni, versioni o ETag del backend.
+
+---
+
+## 15. Relazione con MCP e WebMCP
+
+### MCP
+
+MCP resta per vops il canale operativo principale.
+
+La Surface fornisce:
+
+```text
+attenzione + riferimenti + presentazione
+```
+
+MCP fornisce:
+
+```text
+dati autorevoli + capability + guardrail + esecuzione
+```
+
+### WebMCP
+
+WebMCP viene trattato come prior art complementare, non come dipendenza.
+
+In termini concettuali:
+
+```text
+Semantic Surface
+Che cosa è stato presentato e a cosa si riferisce “questo”?
+
+WebMCP / MCP
+Quali azioni o strumenti sono disponibili?
+```
+
+La v0.2 non introduce API browser proprietarie nel core.
+
+Il formato JSON potrà essere trasportato tramite:
+
+- body di una richiesta applicativa;
+- content block o resource MCP;
+- script JSON in SSR;
+- bridge in-browser;
+- eventuali API browser future.
+
+---
+
+## 16. `requestAttention` e interazione agente→UI
+
+La proposta `reveal/highlight` è interessante e coerente con il modello di attenzione.
+
+Non viene però inserita nella v0.2 core.
+
+Motivi:
+
+- introduce un canale bidirezionale distinto;
+- richiede policy sul focus;
+- richiede un modello di consenso o rifiuto;
+- ha implicazioni di accessibilità;
+- necessita di regole anti-phishing;
+- non è necessaria per dimostrare il valore della Surface.
+
+Viene registrata come possibile estensione futura:
+
+```text
+SS-ATTENTION
+```
+
+Vincolo già deciso per un’eventuale estensione:
+
+> potrà chiedere di portare o evidenziare l’attenzione, ma non potrà eseguire azioni di dominio, inviare form o modificare dati.
+
+---
+
+## 17. Binding DOM opzionale
+
+Un binding web può associare un elemento DOM a uno scope:
+
+```html
+<section data-surface-scope="server-metrics">
+  ...
+</section>
+```
+
+Questo attributo:
+
+- non è obbligatorio nel wire format;
+- non contiene i dati semantici;
+- non sostituisce lo snapshot;
+- permette a un host che dispone di DOM e pixel di calcolare il bounding box on demand;
+- evita di inserire coordinate instabili nello snapshot.
+
+È una capacità del binding web, non del core.
+
+---
+
+## 18. Struttura documentale adottata
+
+Non vengono creati immediatamente quattro standard separati.
+
+Per la v0.2 si propone:
+
+```text
+spec/
+  semantic-surface-core.md
+  semantic-surface.schema.json
+
+pilots/
+  vops-semantic-surface.md
+
+packages/
+  semantic-surface-core/
+  semantic-surface-alpine/
+```
+
+### `semantic-surface-core.md`
+
+Contiene:
+
+- definizione;
+- wire format;
+- regole normative;
+- trust boundary;
+- redazione;
+- budget;
+- versioning;
+- criteri minimi di conformità.
+
+### `semantic-surface.schema.json`
+
+Valida:
+
+- struttura;
+- campi obbligatori;
+- formati;
+- limiti di base;
+- ref;
+- revision;
+- scope;
+- observation.
+
+### `vops-semantic-surface.md`
+
+Contiene:
+
+- integrazione Alpine;
+- collegamento al registry MCP;
+- pagina pilota;
+- domande di test;
+- misure;
+- limitazioni del pilot.
+
+Lo split completo tra runtime, bindings e authoring guide avverrà soltanto dopo che una seconda implementazione avrà evidenziato reali differenze.
+
+---
+
+## 19. Pilot vops aggiornato
+
+### Pagina
+
+```text
+Server Details
+```
+
+### Contesto da esporre
+
+- entità primaria;
+- nome presentato;
+- tab attivo;
+- eventuale deployment selezionato;
+- loading/error/empty;
+- CPU e memoria presentate;
+- timestamp delle metriche;
+- riferimenti MCP per dati aggiornati;
+- completezza di eventuali liste.
+
+### Contesto da non esporre
+
+- capability hint;
+- permessi;
+- risk level;
+- approval policy;
+- dati completi delle metriche;
+- log completi;
+- relazioni di dominio non necessarie;
+- segreti;
+- riepiloghi inventati per il modello.
+
+### Domande positive
+
+1. «Che server sto guardando?»
+2. «Come sta andando quello selezionato?»
+3. «Perché questa CPU è alta?»
+4. «Mostrami i processi che stanno consumando di più.»
+5. «Riavvia questo server.»
+6. «Analizza il deployment selezionato.»
+
+### Controlli negativi
+
+1. Una domanda su un server non visibile non deve essere risolta usando il server corrente.
+2. Una pagina senza selezione non deve inventare una selezione.
+3. Un valore stantio non deve essere presentato come stato corrente senza verifica.
+4. Testo malevolo nei log non deve diventare istruzione per l’agente.
+5. Una capability non disponibile non deve essere inferita dalla UI.
+6. Il cambio di pagina durante il reasoning deve produrre una risposta marcabile come basata sulla vista precedente.
+
+---
+
+## 20. Metriche del pilot
+
+Il pilot deve confrontare almeno due configurazioni:
+
+```text
+A. Assistente + MCP senza Semantic Surface
+B. Assistente + MCP con Semantic Surface
+```
+
+A parità di:
+
+- modello;
+- system prompt;
+- tool MCP;
+- autorizzazioni;
+- dataset;
+- temperatura;
+- numero massimo di turni.
+
+### Metriche principali
+
+- percentuale di risoluzione corretta dell’entity ref;
+- percentuale in cui il primo tool call contiene l’ID corretto;
+- numero di tool call prima del grounding corretto;
+- numero di richieste di chiarimento;
+- precisione della prima capability scelta;
+- numero di errori deittici;
+- byte e token aggiunti dalla Surface;
+- risposte basate su dati stantii;
+- contenimento delle stringhe ostili;
+- tasso di false associazioni nelle domande negative.
+
+### Claim consentito
+
+Se il pilot ha successo, possiamo affermare:
+
+> La Semantic Surface migliora il grounding contestuale di un assistente vops dotato di strumenti MCP su una specifica UI a pagina singola.
+
+Non possiamo ancora affermare:
+
+- portabilità universale;
+- sicurezza cross-origin;
+- efficacia su ogni framework;
+- efficacia su CLI, TUI o voce;
+- idoneità a diventare standard web;
+- riduzione generale dei costi per ogni applicazione.
+
+---
+
+## 21. Criteri di accettazione aggiornati
+
+Il pilot è considerato riuscito quando:
+
+1. la Surface è conforme allo JSON Schema;
+2. l’assistente identifica il server corrente senza nome esplicito;
+3. la modifica della selezione cambia l’entity ref;
+4. uno scope inattivo non compare nello snapshot;
+5. loading, error ed empty state sono distinguibili;
+6. una lista troncata dichiara la propria incompletezza;
+7. nessun segreto compare nello snapshot;
+8. non sono presenti capability hint;
+9. le mutazioni usano ID espliciti nei tool call;
+10. MCP rivalida autorizzazione, stato e approvazione;
+11. lo snapshot resta entro il budget configurato oppure dichiara il troncamento;
+12. la risposta conserva la revision di origine;
+13. la UI continua a funzionare se la generazione della Surface è disabilitata;
+14. la configurazione con Surface supera le soglie di uplift definite prima del test.
+
+---
+
+## 22. Cosa viene esplicitamente rinviato
+
+La v0.2 non tenta di risolvere:
+
+- standardizzazione W3C;
+- registry universale dei vocabolari;
+- JSON-LD o RDF;
+- firma dei provider;
+- composizione cross-origin;
+- capability registry universale;
+- navigation model;
+- funnel automation;
+- form prefilling;
+- click automation;
+- annotazioni persistenti dell’agente;
+- condivisione cross-device;
+- persistenza della Surface;
+- requestAttention;
+- equivalenza completa tra web, CLI, TUI e voce;
+- generazione automatica completa da Flui.
+
+Questi temi restano ipotesi o possibili estensioni. Non sono requisiti del pilot.
+
+---
+
+## 23. Roadmap proposta
+
+### Fase 1 — Core v0.2
+
+- definire `semantic-surface.schema.json`;
+- ridurre il modello dati;
+- eliminare relation, sensitivity e capabilityHints;
+- introdurre attention array, state e completeness;
+- definire ref canonico;
+- definire regole di redazione e budget.
+
+### Fase 2 — Builder vops
+
+- implementare definizioni pure sopra lo state esistente;
+- generare snapshot lazy;
+- aggiungere inspector;
+- misurare dimensione e churn;
+- verificare che non esista uno stato semantico parallelo.
+
+### Fase 3 — Integrazione assistant
+
+- allegare snapshot e revision al messaggio;
+- trattare lo snapshot come dato non attendibile;
+- usare entity ref espliciti;
+- verificare dati freschi tramite MCP;
+- mantenere capability e autorizzazione lato server.
+
+### Fase 4 — Esperimento controllato
+
+- preparare prompt e domande;
+- definire soglie prima del test;
+- eseguire configurazione A/B;
+- analizzare errori positivi e negativi;
+- decidere se il beneficio giustifica il costo.
+
+### Fase 5 — Seconda implementazione
+
+Solo dopo il successo del pilot:
+
+- binding Angular/Flui oppure implementazione SSR;
+- verifica della portabilità;
+- split completo dei documenti;
+- valutazione di un’estensione attention;
+- eventuale proposta pubblica.
+
+---
+
+## 24. Decisione finale
+
+La revisione tecnica viene accolta come miglioramento sostanziale, ma non viene adottata nella sua forma più prescrittiva.
+
+La direzione consolidata è:
+
+> **La Semantic Surface non è un digital twin della pagina e non è un catalogo di capability. È uno snapshot compatto, serializzabile e non autorevole dell’attenzione dell’utente e di ciò che la UI gli ha presentato.**
+
+Il backend e MCP restano responsabili di:
+
+- verità corrente;
+- dati completi;
+- capability;
+- autorizzazioni;
+- approvazioni;
+- esecuzione.
+
+Il client resta responsabile di:
+
+- presentazione;
+- selezione;
+- focus;
+- stato della vista;
+- snapshot.
+
+L’assistente resta responsabile di:
+
+- interpretare il linguaggio naturale;
+- collegare la deissi alle entity ref;
+- verificare i dati tramite MCP;
+- scegliere strumenti autorizzati;
+- non confondere la Surface con una fonte autorevole.
+
+La v0.2 dovrà essere abbastanza precisa da poter essere implementata e misurata, ma abbastanza piccola da poter essere scartata o modificata senza aver costruito prematuramente un nuovo standard web.