docs(website): document the run-result format as a stable contract - #80
Open
AndreasKoestler wants to merge 1 commit into
Open
docs(website): document the run-result format as a stable contract#80AndreasKoestler wants to merge 1 commit into
AndreasKoestler wants to merge 1 commit into
Conversation
Add a reference page describing .var/<spec>.json (SpecResults), the fnv1a: sourceHash fingerprint, span-anchored CellFailure semantics, the staleness contract, and the var.lock.json drift baseline. Declare the stability policy: additive optional fields without a version bump, breaking changes bump version, unknown versions treated as absent, and the hash algorithm versioned independently via its prefix. Also fixes the dead examples-and-drift.mdx links in ADR 0002 and points CLAUDE.md at the new stable doc instead of calling the format emerging. Refs varar-dev#66
This was referenced Aug 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #66.
Adds a reference page, Run results, documenting the run-result format as a stable, machine-readable contract:
.var/<spec>.json, one record per spec, git-ignored, written by the vitest reporterSpecResults/ExampleResult/CellFailurewith annotated passing + failing examples;expectedrecovered by slicing source at the recorded offsets;ReturnShapeError/plain errors carry message+stack onlysourceHash— FNV-1a 32-bit over UTF-16 code units,fnv1a:prefix, pinned test vectors for consumer reimplementation, and the staleness contract (hash mismatch → consumer must not render)var.lock.jsonshape, byte-stable serialization, acknowledgment flows (var run --update,VAR_UPDATE=1, LSPvar.acceptDrift), vitest as read-only gateversion; consumers must ignore unknown fields and treat unknown versions as absent; the hash algorithm is versioned independently via its prefix. Aimed at long-lived consumers (supervising agents, CI gates, CRA attestation pipelines)specPath, 2-space JSON + trailing newline; per-port emitter status table (TS today; py/java/ruby/rust planned)Drive-bys: CLAUDE.md now points at the stable doc instead of calling the format "emerging"; ADR 0002's dead
examples-and-drift.mdxlinks fixed (examples.mdx).Notes
varar.lock.json— the actual filename isvar.lock.json; the page documents the real name.var run --jsonreporter, and run-record emitters for the Python/Java/Ruby/Rust ports.Verification
pnpm --filter @oselvar/website build— content sync accepts the new page (build then fails on a pre-existingTabItem/unified prerender error onhow-to/tables-and-doc-strings, unrelated to this change)var-core/src/{result,hash,drift,failure,run-diagnostics}.ts,var-vitest/src/reporter.ts,var-cli/src/run.ts, andvar-lsp/src/store.ts