Verisyntax — brugermanual (prototype 0.1)

Claims, evidens og godkendelse

Metadata-schemaet skal være installeret, og et claim skal referere mindst én eksisterende mention fra en synlig, gemt source-version. Opret først en lokal reviewer-identitet:

Et præcist mention fra en lokal TXT/Markdown-source-version kan oprettes med UTF-8 byte-offsets:

<compiler>/verisyntax mentions capture model.vsx local SOURCE_VERSION_ID \
  --start 120 --end 184
<compiler>/verisyntax mentions list model.vsx local --limit 100

Før insertion læser C++ den absolutte lokale snapshot-sti fra source-versionen, genberegner hele filens SHA-256, kræver text/plain eller text/markdown, kontrollerer offsets og UTF-8 boundaries og hasher det eksakte excerpt. Hvis filen er ændret siden source-versionen, oprettes intet mention. CLI-flowet kræver en absolut sti, begrænser snapshotet til 64 MiB før indlæsning og excerptet til 100.000 bytes.

IDE'ens grafiske range-picker bruger to eksplicitte kommandoer:

Åbn .vsx-filen og vælg Open Text Snapshot for Evidence Selection. Vælg metadata-database og derefter en gemt TXT/Markdown-source-version.
C++ begrænser det grafiske preview til 4 MiB, verificerer hele snapshotets SHA-256 og UTF-8 og åbner indholdet gennem den skrivebeskyttede URI-type verisyntax-snapshot.
Markér det eksakte tekstudsnit og vælg Capture Selected Snapshot Text as Evidence.
IDE'en konverterer editorens UTF-16-positioner til UTF-8-byteoffsets og viser source-version, source-hash, byteinterval, dokumenthash og excerpt før bekræftelse.
C++ kontrollerer dokumenthash, læser originalsnapshotet igen, genberegner filhash og validerer UTF-8-grænserne før mentionet gemmes atomisk.

Et preview eller en markering skaber aldrig selv et claim, fact eller en regel. Filer over 4 MiB kan fortsat anvendes via CLI'ens eksplicitte byteoffsets op til 64 MiB.

For at gøre evidensen uafhængig af originalfilens senere placering eller ændringer kan snapshotet kopieres ind i projektets content-addressed lager:

<compiler>/verisyntax mentions retain model.vsx local SOURCE_VERSION_ID

Eller vælg Retain Text Snapshot Locally i IDE'en. C++ verificerer først hele originalfilen mod source-versionens SHA-256, kopierer atomisk til <snapshot-storage> og registrerer original URI, retained URI, hash, byteantal og tidspunkt i source_snapshots. Gentagelse er idempotent og genverificerer den eksisterende kopi. Preview og mention-capture foretrækker derefter retained copy; original URI overskrives aldrig. Snapshotmappen er Git-ignoreret som standard, fordi den kan indeholde følsomt kildemateriale.

En konkret celle fra en godkendt CSV/JSON/TXT/XLSX-import kan bindes direkte som evidens:

<compiler>/verisyntax mentions cells model.vsx local --limit 100
<compiler>/verisyntax mentions capture-cell model.vsx local SOURCE_CELL_ID

C++ følger cellen gennem source_cell -> source_record -> import_run -> source_version, afviser ukendte celler og parse-fejl og gemmer både record- og cell-ID. Excerptet viser den oprindelige pointer, kolonne og rå værdi, eksempelvis csv:line:2 | name = Customer A; offsets er tomme for tabelobservationer. I IDE'en viser Capture Imported Cell as Evidence op til 100 gemte celler med værdi, parse-status og provenance. Først efter en modal bekræftelse og kontrol af dokumenthash oprettes mentionet. Handlingen opretter ikke et claim, fact eller en regel.

I den selvstændige desktopapp er den præcise knaprækkefølge Load imported cells → vælg celle → Capture selected mention → vælg et eller flere mentions → Suggest claim locally. Den valgte model og 64K/128K hentes fra LOCAL AI-kortet. Det validerede JSON-forslag bliver stående i et redigerbart felt. Store reviewed proposal opretter kun en inaktiv claim-version; Approve as fact eller Reject claim kræver derefter en separat begrundelse og bekræftelse af versionens eksakte hash. Appen viser output og auditoplysninger i Artifact og Results.

<compiler>/verisyntax profile set model.vsx \
  --actor-id local:analyst-1 \
  --display-name "Local Analyst"
<compiler>/verisyntax profile show model.vsx

Profilen gemmes atomisk i <managed-storage> ved siden af projektet. Verisyntax læser ikke brugeridentitet fra macOS, og profilen sendes ikke til en cloudtjeneste. En senere ændring kræver den aktuelle profile_hash som --expected-hash, så en identitet ikke kan skiftes ubemærket efter review.

Claim-review viser nu hvert evidensobjekt, ikke kun et antal. Evidensen grupperes under de engelske roller supports, contradicts og context og viser source-version, URI, source-/mention-hash, record/cell, pointer/column, byteinterval og excerpt. Integritetsstatus er én af:

verified: retained/original fil matcher source-hash, offsets og excerpt;
stored_cell_binding: mentionet er bundet til en konkret importeret record og celle;
source_unavailable: filen kan ikke længere læses sikkert;
source_hash_mismatch: filens aktuelle bytes matcher ikke source-versionen;
excerpt_mismatch: offsets peger ikke længere på det lagrede excerpt;
mention_hash_mismatch: selve mention-excerptet matcher ikke dets lagrede hash;
metadata_only: mentionet har ikke et verificerbart filinterval eller en cellebinding.

En advarende integritetsstatus blokerer ikke read-only-inspektion og omskriver aldrig historik. Brugeren kan afvise claimet eller oprette en ny version med bedre evidens. Approval er stadig en separat exact-hash-bundet handling.

Et manuelt eller lokalt genereret forslag bruger denne kontrakt:

{
  "schema": "verisyntax.claim-proposal",
  "version": 1,
  "stable_name": "reported_value",
  "claim": {
    "subject": "report",
    "relation": "reported_value",
    "object": 42
  },
  "extraction_confidence": 0.91,
  "evidence": [
    {"mention_id": "mention-1", "role": "supports"}
  ]
}

claim skal være et ikke-tomt JSON-object. Evidensrollen er supports, contradicts eller context. extraction_confidence er valgfri og betyder kun sikkerhed på udtrækning/strukturering; den er ikke sandsynligheden for, at claimet er sandt.

Gem forslaget som en ikke-faktuel review-version, og list derefter det præcise content hash:

<compiler>/verisyntax claims propose model.vsx local proposal.json
<compiler>/verisyntax claims list model.vsx local --status proposed

Godkendelse eller afvisning kræver claim-versionens ID og hash fra listen:

<compiler>/verisyntax claims decide model.vsx local CLAIM_VERSION_ID approve \
  --expected-hash CLAIM_CONTENT_HASH \
  --reason "Evidence excerpt checked"

<compiler>/verisyntax claims decide model.vsx local CLAIM_VERSION_ID reject \
  --expected-hash CLAIM_CONTENT_HASH \
  --reason "Evidence does not support the exact wording"

Godkendelse opretter et fact med præcis den reviewede claim-JSON og deaktiverer et tidligere aktivt fact for samme stabile claim. Afvisning opretter aldrig et fact. Begge beslutninger gemmer reviewer, tidspunkt, reason og tidligere content hash. Ændringer opretter en ny claim-version; historikken overskrives ikke.

I IDE'en er rækkefølgen:

Configure Local Review Identity.
Propose Claim From JSON og godkend, at den validerede version må gemmes som proposed.
Review Claims; kontrollér exact JSON, evidence count, creator, status og content hash i det scriptfri panel.
Approve or Reject Claim; vælg den eksakte version, eventuel reason og bekræft den separate modal.

C++ genkontrollerer dokumenthash, reviewer-profilhash og claim-content-hash før en beslutning. Hvis noget er ændret efter visningen, afvises mutationen, og review skal gentages. En godkendelse kan derfor ikke ramme en anden buffer, identitet eller claim-version end den, brugeren så.