Skip to content

docs(website): document the run-result format as a stable contract - #80

Open
AndreasKoestler wants to merge 1 commit into
varar-dev:mainfrom
AndreasKoestler:docs/run-result-format
Open

docs(website): document the run-result format as a stable contract#80
AndreasKoestler wants to merge 1 commit into
varar-dev:mainfrom
AndreasKoestler:docs/run-result-format

Conversation

@AndreasKoestler

Copy link
Copy Markdown
Contributor

Summary

Closes #66.

Adds a reference page, Run results, documenting the run-result format as a stable, machine-readable contract:

  • File layout.var/<spec>.json, one record per spec, git-ignored, written by the vitest reporter
  • Record shapeSpecResults / ExampleResult / CellFailure with annotated passing + failing examples; expected recovered by slicing source at the recorded offsets; ReturnShapeError/plain errors carry message+stack only
  • sourceHash — 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)
  • Drift baselinevar.lock.json shape, byte-stable serialization, acknowledgment flows (var run --update, VAR_UPDATE=1, LSP var.acceptDrift), vitest as read-only gate
  • Stability policy — additive optional fields without a version bump; breaking changes bump version; 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)
  • Cross-language rules — UTF-16 offsets, POSIX 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.mdx links fixed (examples.mdx).

Notes

  • The issue comment mentioned varar.lock.json — the actual filename is var.lock.json; the page documents the real name.
  • Follow-up issues filed separately: var run --json reporter, 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-existing TabItem/unified prerender error on how-to/tables-and-doc-strings, unrelated to this change)
  • All field names, hash vectors, CLI flags, and LSP command names checked against var-core/src/{result,hash,drift,failure,run-diagnostics}.ts, var-vitest/src/reporter.ts, var-cli/src/run.ts, and var-lsp/src/store.ts

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document the run-result format as a stable, machine-readable contract

1 participant