Session Explorer e risorse

Versione verificata

1. Session files non è un file manager generale

La scheda Session files attraversa soltanto la Session corrente e mostra file text-like supportati. Non permette di navigare liberamente il filesystem.

Le estensioni accettate nella dev-031 sono:

.txt .csv .tsv .md .ini .log .json .yaml .yml .cfg .dat .asc .cir .net .lib

I plot sono esclusi perché hanno un workflow di visualizzazione dedicato.

2. Barra superiore

• Refresh — riscan della Session corrente.
• Copy file text — copia il testo della preview.
• Info — mostra Session path e conteggio dei file text/data rilevati.

3. Tree dei file

Il pannello sinistro ricostruisce le directory relative alla Session. Ogni file è risolto contro la root corrente; un path fuori Session viene rifiutato.

Selezionare o fare doppio click su un file apre la preview read-only nel pannello destro. File non supportati non vengono presentati come testo.

4. Preview e limite di sicurezza

Il reader usa UTF-8 e limita la preview. Nella dev-031 sessionFileMaxBytes è 4.194.304 byte. Se il file è più grande, vengono letti soltanto i primi 4 MiB e viene aggiunto un messaggio di troncamento.

5. Session Script Explorer

Nella stessa pagina, sotto il file explorer, la dev-031 elenca gli script registrati con scope Session. Le colonne sono:

Selezionando uno script, la riga informativa mostra anche SHA-256 completo, required APIs e descrizione.

I pulsanti disponibili sono Open in Script Library e Run selected. Il doppio click apre lo script nella Script Library.

6. Identità dello script di Session

Lo script registrato ha riferimento qualificato session:<id>. È uno snapshot fisico separato da un eventuale script user:<id>. Una modifica successiva alla User Library non riscrive silenziosamente la copia assegnata alla Session.

Ogni esecuzione conserva snapshot, log, report ed execution.ini sotto analysis/scripts/<run_id>/.

7. File visibile ≠ risorsa logica

Molte risorse persistenti sono implementate tramite file INI, JSON o sidecar, ma il file non è il loro contratto pubblico. La risorsa è identificata da un ID e deve essere usata attraverso l'API semantica che la possiede.

8. Dataset

I Dataset sono indicizzati da metadata/datasets.ini, ma consumer e script devono usare Dataset API. Il Dataset ID e i Variable ID restano le identità stabili.

Dataset Metadata può vivere in sidecar sotto metadata/datasets/; Dataset Notes può vivere sotto notes/datasets/. Sono risorse distinte.

9. Dataset Selections

Le Selection persistenti usano ID come sel_001 e tipi x_range o rectangle. Sono normalmente registrate in metadata/dataset_selections.ini.

Una Selection non copia né filtra fisicamente il Dataset. Descrive un intervallo riusabile attraverso identità Dataset/Variable stabili e coordinate.

10. Temporal Sets

Le Temporal Set persistono definizioni come tset_001. Possono essere segment_set o window_set e vivono come viste temporali sopra un Dataset canonico.

Il registry corrente è metadata/temporal_sets.ini. Le finestre generate non vengono necessariamente persistite una per una: la definizione autorevole viene risolta quando serve.

11. Interactive Documents

Interactive Document API memorizza stato UTF-8 autorevole appartenente a strumenti interattivi che non può essere ridotto a metadata, viewer state o cache. Gli ID sono del tipo idoc_0001.

Il documento appartiene alla Session e a un owner module/provider. Runtime o cache possono essere ricostruiti senza cancellare il documento autorevole.

12. Plot, Variant, viewer scene e layers

Plot e Viewer conservano presentation state persistente. Un Plot Variant non è soltanto un PNG: possiede identità e configurazione persistente. Analogamente scene e layers dei viewer devono passare dalle relative API pubbliche.

I file derivati visibili nella Session possono essere utili per ispezione, ma non sono automaticamente il luogo corretto da modificare.

13. Manifest e Session Persistence

metadata/manifest.ini conserva lo stato framework-owned principale della Session: moduli, configurazioni, bindings, graph state e altri elementi registrati. Session Persistence API v1 può commitare semanticamente lo stato della Session corrente.

La regola è: prima usare l'API proprietaria della risorsa — Dataset Publication, Plot Dataset, Viewer Provider, Selection, Interactive Document — e usare Session Persistence quando serve salvare lo stato complessivo corrente.

14. Session Inspection API

Per exporter e strumenti di presentazione esiste una superficie read-only che espone summary, Dataset IDs, Dataset details, Selections e file inventory senza costringere il consumer a leggere layout privati del registry.

Può anche risolvere risorse Session-relative, verificare SHA-256 e produrre uno snapshot di ispezione.

15. Portabilità della Session

Export Session... crea un package portabile lossless con manifest di trasporto, inventario file, dimensioni e SHA-256. Import valida l'archivio, usa staging e commette solo dopo verifica completa.

Gli ID scientifici della Session non vengono rigenerati soltanto perché la Session viene esportata/importata.

16. Cosa puoi modificare direttamente dal file explorer?

La preview è intenzionalmente read-only. Alcuni file di note possono aprire strumenti di editing dedicati attraverso altre parti di GX-TXT, ma Session files non è il posto dove alterare registri e manifest.

17. Mappa rapida delle risorse

• Introduzione a GX-TXT.
• Dataset e Variable ID.
• Octave & Python Script Workspaces.
• Guida alle API reference utilizzabili con Script Bridge.
• Projects, Experiments e Sessions — relazione fra la Session corrente, l'Experiment e il Project.