VerisyntaxEvidence-oriented language
Under udviklingVerisyntax er en lokal prototype. Funktioner, syntaks og dokumentation kan ændre sig.

Verisyntax — brugermanual (prototype 0.1)

CSV- og JSON-import

Preview er standard og åbner eller opretter ikke databasen:

<compiler>/verisyntax import csv model.vsx customers customers.csv --mode preview --preview-rows 10

CSV-headeren kan matche en logical column (id) eller dens physical mapping (customer_id). Begge må ikke optræde samtidig. Ikke-mappede CSV-kolonner vises som advarsler; hele den rå række bevares stadig i provenance.

En eksplicit mapping kan bruges, når inputnavnene er anderledes. Hver deklareret logical column skal have præcis ét eksisterende inputfelt, og et inputfelt må ikke genbruges:

<compiler>/verisyntax import csv model.vsx customers customers.csv \
  --map id="Customer No" --map name="Display Name" --mode preview

CLI-resultatet viser et canonical mapping_hash. IDE'en udfører denne mapping interaktivt efter en databasefri feltinspektion.

En ny destination kræver eksplicit create:

sqlite3 <data-storage>/verisyntax.sqlite < schema/sqlite/001_metadata.sql
<compiler>/verisyntax import csv model.vsx customers customers.csv --mode create

En eksisterende, kompatibel tabel kræver eksplicit append:

<compiler>/verisyntax import csv model.vsx customers next-customers.csv --mode append

Importmotoren understøtter UTF-8 BOM, CRLF/LF, quoted fields, escaped quotes og newlines i quoted fields. Den validerer header, field count, typer, required/optional, destinationskolonner, databasetyper og nullability før eller under transaktionen. Standardgrænserne er 64 MiB og 100.000 datarækker. create afviser en eksisterende tabel; append afviser en manglende tabel. Der er med vilje ingen replace endnu.

En eksisterende tabel kan opdateres uden sletninger gennem et reviewet primary-key merge. Sourcen skal deklarere primary_key, og inputtet må ikke gentage en nøgle:

preview=$(<compiler>/verisyntax import csv model.vsx customers changed-customers.csv \
  --mode merge-preview --preview-rows 50)
printf '%s\n' "$preview"
plan_hash=$(printf '%s\n' "$preview" | sed -n 's/^merge_plan_hash=//p')
<compiler>/verisyntax import csv model.vsx customers changed-customers.csv \
  --mode merge --expected-merge-plan "$plan_hash" --preview-rows 0

merge-preview indlæser en midlertidig staging-tabel, klassificerer hver indkommende række som inserted, updated eller unchanged, viser ændrede non-key columns og ruller preview-transaktionen tilbage. Planhashen binder dokument, fil, mapping, nøgler, indkommende værdier og de aktuelle destinationsværdier. Commit gendanner hele planen i én transaktion og afviser den, hvis dokument, fil, mapping eller destination er ændret siden preview. Merge opdaterer kun ændrede non-key columns, indsætter nye keys, gemmer uændrede observationer i provenance og sletter aldrig destinationsrækker.

Typed rows, source_version, import_run, source_record, source_cell og import_warning skrives i samme transaktion. En constraint- eller databasefejl ruller hele batchen og dens nye provenance tilbage. Den samme motor bruges til SQLite og PostgreSQL. PostgreSQL-adgang hentes fortsat kun fra den deklarerede environment variable.

JSON bruger den samme preview/create/append-motor:

<compiler>/verisyntax import json model.vsx customers customers.json --mode preview --preview-rows 10
<compiler>/verisyntax import json model.vsx customers customers.json --mode create

Første JSON-adapter kræver et ikke-tomt top-level array af flade objekter. Tilladte værdier er string, boolean, integer, finite number og null. Nested objects/arrays afvises synligt og bliver ikke automatisk fladet ud. JSON-typen skal svare til source-typen; missing eller null er kun gyldig for en optional column. En tom string forbliver en tom string og adskilles fra null. Preview er databasefri, standardgrænserne er 64 MiB og 100.000 items, og commit genkontrollerer dokument-, fil- og mapping-hash. Provenance gemmer den præcise filhash, den godkendte mapping, et canonical JSON-object pr. række samt pointeren json:item:N med én-baseret itemnummer.

CSV-import i IDE'ens Data Workspace

Den første Data Workspace-arbejdsgang er implementeret i VS Code-klienten:

  1. Åbn den relevante .vsx-fil, og kør Verisyntax: Preview CSV Import.
  2. Vælg en deklareret source, en lokal CSV-fil og delimiter (komma, semikolon eller tabulator). C++ inspicerer feltnavne, row count og filhash uden databaseadgang.
  3. Vælg ét unikt CSV-felt for hver deklareret logical column. Forslag, der matcher logical eller physical name, markeres, men anvendes ikke uden dit valg.
  4. Kontrollér destination, dokumenthash, filhash, mapping-hash, row count, CSV→logical→physical mappings, datatyper, NULL/tomme strenge, ignorerede kolonner og advarsler i preview-panelet. Preview er scriptfrit og ændrer ikke databasen.
  5. Initialisér metadata-schemaet på destinationen, hvis det ikke allerede findes.
  6. Kør Verisyntax: Commit Last CSV Preview, vælg create, append eller Prepare staging merge, og godkend den modale opsummering.

Create/append sender de tre hashes fra den seneste preview tilbage til C++-serveren. Merge åbner først et særskilt, scriptfrit staging-diff med current/incoming values, row action, ændrede columns, handlingsantal og en fjerde planhash. Intet er committed på dette tidspunkt. Kør derefter Verisyntax: Commit Last Merge Plan og godkend den eksakte plan, som viser inserts, updates, unchanged observations, Deletes: 0 og alle fire hashes. Hvis dokument, fil, mapping eller destinationsværdier er ændret, afvises hele committen. Den godkendte mapping gemmes i mapping_json, og hver source-record gemmer sin destination-action. Der findes ingen skjult replace eller automatisk delete.

JSON har den parallelle arbejdsgang Verisyntax: Preview JSON Import og Verisyntax: Commit Last JSON Preview. Preview viser JSON itemnummer, den valgte input-field→logical→physical mapping, null/tomme strings, ignored fields, alle tre hashes og destination. Commit har samme modale godkendelse, hashkontrol og udelukkende create/append.

Almindelig tekst har tilsvarende kommandoer Preview Line Text Import og Commit Last Line Text Preview samt CLI-formatet import text. Adapteren er med vilje entydig: hver fysisk linje er én række, source skal have præcis én column, tomme indre linjer bevares som tomme strings, og provenance bruger text:line:N. Den forsøger ikke at gætte delimiter, felter eller afsnit.

XLSX bruger CLI-formatet import xlsx og kræver eksplicit sheet-navn, når workbooken har flere ark:

<compiler>/verisyntax import xlsx model.vsx orders sales.xlsx --sheet Orders --mode preview

I IDE'en vælger Preview XLSX Import først fil, derefter et sheet fra workbookens egne relationer og til sidst den eksplicitte feltmapping. Preview og Commit Last XLSX Preview bruger samme triple-hash-godkendelse som de øvrige formater. Importen læser XLSX lokalt gennem versionslåste C/C++-biblioteker, begrænser både komprimeret filstørrelse og samlet udtrukket XML, dekoder shared/inline strings, booleans og numeriske celler og bevarer xlsx:sheet:<name>!row:<N> samt den originale column i cell-provenance. Manglende celler kræver optional. Formelceller og Excel-fejlceller afvises i første version, så en cached formelværdi ikke fejlagtigt behandles som frisk evidens. Numeriske Excel-datoceller konverteres endnu ikke implicit; brug ISO-8601-værdier eller en eksplicit senere mapping.

Importhistorik

Tidligere imports kan læses fra det valgte SQLite- eller PostgreSQL-metadatalager uden mutation:

<compiler>/verisyntax import-runs list model.vsx local --limit 50

I IDE'en bruges Verisyntax: Show Import History. Vælg database og godkend den read-only forespørgsel. Det scriptfri panel viser højst 100 runs med import-ID, source/version, præcis filhash og URI, format/sheet, destination, operation, inserted/updated/unchanged counts, status/tider, antal gemte records, den godkendte input→logical→destination-mapping og højst 100 warning-detaljer pr. run. Dokumenthashen genkontrolleres før forbindelsen åbnes. Visningen genkører aldrig en import. En filhash dokumenterer byte-identitet, ikke at kildens indhold er sandt eller aktuelt.

Brug Verisyntax: Browse Imported Records for at inspicere den gemte række- og celleprovenance for ét valgt import-run. Først godkendes den read-only run-liste, derefter vælges det præcise run og record-læsningen godkendes særskilt. Panelet viser højst 100 records med source pointer, record key og content hash samt hver celles originale inputfelt, logical/physical column, raw value, parsed JSON og parse status. Rå payloads begrænses til 16K tegn og celleværdier til 4K tegn med synlige truncation-markører. Dette er gemte provenance-snapshots, ikke en live læsning af destinationstabellen. CLI-ækvivalenten er:

<compiler>/verisyntax import-runs records model.vsx local <import-run-id> --limit 50

Denne første UI bruger det allerede deklarerede schema og udfører ikke automatisk type- eller join-inferens. Redigerbar importmapping, reviewet staging/merge, importhistorik, persisted record/cell browser, schema browser, source-udkast, live source-grid og two-source join composer er implementeret; schemaændringer, replacement/deletes og multi-join composition er fortsat planlagt. Den fulde UI-kontrakt står i IDE_PLAN.md.