corankai/ai-citation-evidence-validator

Purpose and delivery model

This repository provides a dependency-free, browser-local validator for AI-search/AEO/GEO observation records. It accepts pasted JSON arrays or JSONL, evaluates explicit evidence-quality rules, and produces inspectable record/field findings rather than an aggregate visibility score. Static deployment is centered on index.html, with the published tool intended for GitHub Pages.

Paths: index.html, script.js, style.css

Primary browser entry point

index.html hosts the interactive input, validation controls, findings display, and local report-download surface. script.js is the application controller: it reads pasted input, selects JSON versus JSONL parsing, invokes validation, renders status/finding output, and creates downloadable JSON in the browser. style.css supplies the presentation layer without a framework or build artifact.

Paths: index.html, script.js, style.css

Observation ingestion boundary

The system’s sole operational input is a collection of observation objects representing prompt-answer runs. Parsing is deliberately client-side and must tolerate either one JSON array or line-delimited JSON objects. Invalid syntax and malformed records are surfaced as validation findings rather than sent to a service. This is the key privacy boundary: pasted evidence remains in the browser.

Paths: script.js, README.md

Validation engine and rule contract

The JavaScript validator enforces schema presence and cross-field consistency: required fields, boolean mention/citation flags, parseable/time-zoned timestamps, cited-domain arrays, target-domain agreement, evidence URLs, claim summaries, prompt-version stability, and duplicate run keys. Errors mark records invalid; warnings retain them for review; only records without findings are ready. Findings remain tied to individual records and fields.

Paths: script.js, validator.go, validator_test.go

Go validation package

A parallel Go package exposes the validation model and rules for programmatic consumers, documentation examples, or future non-browser integrations. doc.go defines the package-level public context; validator.go contains the implementation; Go tests establish the rule behavior. This package is separate from the static-page runtime rather than a backend for the web tool.

Paths: doc.go, validator.go, validator_test.go

Reporting and analyst workflow

The control flow is: paste observations → parse into records → validate each record plus duplicate keys across the set → classify invalid/needs-review/ready → render findings → optionally export a local JSON report. The output is an evidence review queue, not a truth or ranking determination; human reviewers remain responsible for checking answer artifacts and claim support.

Paths: script.js, index.html, README.md

Supporting research and publication assets

Documentation formalizes prompt-set versioning and usage guidance, while notebooks analyze adjacent AI-visibility evidence problems such as role drift, citation gaps, and controlled reruns. The repository uses static-site documentation and has lightweight development support through Vite/StackBlitz, but production requires no build step or application server.

Paths: docs/prompt-set-versioning.md, notebooks/citation-gap-action-queue.ipynb, package.json