entviz

README

entviz-go

Go implementation of entviz (spec v10) — visualize high-entropy values as comparable SVG diagrams.

Status: certified against the v10 conformance corpus ✅

A full, self-contained implementation that passes the shared conformance corpus at Tier A (render model) + Tier B (canonical raster) for every render vector, rejects every error vector, and satisfies every invariant pair (54/54). What's here:

• core.go — the deterministic shared core: alphabets, tokenization + 24-bit quant extension, the SHA-512 fingerprint, ftok median/quartile selection, the Oklab color rules + weighted-RGB edge selection, and grid selection.
• entropy.go — the format-specific parsers (hex, UUID, Ethereum w/ EIP-55, ULID, base58 / bech32 / base32 chains, CESR, LEI, snowflake, SWHID / gitoid semantic-prefix fold, IPFS CID, SSH, …) + the disproof-based alphabet detection and large-input (head / fingerprint-middle / tail) tokenization.
• keccak.go — vendored Keccak-256 for EIP-55 checksum validation.
• pipeline.go — the SVG renderer: geometry, 24-box surround, fingerprint-edge cells, ellipse overlay, color bar + markers, blank-cell map, quartile marks, labels, borders — emitting the normative data-* profile.
• cmd/entviz-conformance — the conformance CLI (the stdin→stdout contract in the entviz repo's compliance/README.md).

The module depends only on the Go standard library.

How to consume

go get github.com/dhh1128/entviz-go

package main

import (
	"fmt"
	"os"

	entviz "github.com/dhh1128/entviz-go"
)

func main() {
	// Render(entropy, targetAR, fontSizePt, note) -> (svg, error).
	// note is *string; pass nil for no note.
	svg, err := entviz.Render("a1b2c3d4e5f6a7b8", 1.0, 12.0, nil)
	if err != nil {
		fmt.Fprintln(os.Stderr, "render rejected:", err)
		os.Exit(1)
	}
	fmt.Print(svg)
}

Render rejects out-of-range parameters (font size must be 6–30 pt, aspect ratio 0.01–100), notes that are not printable ASCII (U+0020–U+007E) or longer than 10 characters, and Ethereum addresses whose EIP-55 mixed-case checksum is invalid (the error names the first mismatched-case position).

Build + test

gofmt -l .                                  # must print nothing
go vet ./...
go test ./... -race -cover                  # unit tests + corpus invariants
go build ./...

Conformance against the golden corpus (requires a checkout of the entviz reference repo as a sibling ../entviz and a Python venv with lxml):

go build -o /tmp/entviz-go-conformance ./cmd/entviz-conformance

# from a checkout of the entviz reference repo (sibling ../entviz):
PYTHONPATH=src:. python -m compliance.runner \
  --impl-cmd '/tmp/entviz-go-conformance' --tiers AB
# -> 54/54 vectors passed

Spec compliance & versioning

The module version encodes the entviz spec level it is compliant with:

0.<spec-major>.x — e.g. 0.10.x ⇒ compliant with entviz spec v10 (the same convention the Python reference and entviz-rs use, where spec v10 ↔ 0.10.0).

A spec bump (v10 → v11) is a minor release here (0.10.x → 0.11.0); a patch is a module-only change within a spec version. The canonical spec level is the SpecVersion constant in core.go; the per-impl stamp emitted as data-entviz-lib is LibVersion.

CI surfaces spec drift: the conformance job checks out the public entviz reference, compares its SPEC_VERSION to this module's, and runs the Tier-A conformance suite. When the reference spec is ahead of this module it warns loudly (without blocking unrelated PRs); when the versions match (or this module is ahead) conformance is a hard gate.

Releasing

Go has no central package registry to push to — pkg.go.dev indexes the module straight from a pushed Git tag — so a "release" here is creating the version tag and the GitHub release.

Releases are human-run (agents must not push tags). From a clean, in-sync main, bump the LibVersion constant in core.go, commit, then tag and push:

git tag v0.10.0
git push origin v0.10.0

The tag triggers .github/workflows/release.yml, which re-runs the full gate set (gofmt + vet + go test -race + Tier-A conformance), verifies the tag matches LibVersion, and creates the GitHub release. pkg.go.dev then indexes the new tag automatically.

Sister projects

• entviz — the Python reference implementation and the canonical spec (docs/spec.md), plus the gallery and the shared conformance corpus this module is certified against.
• entviz-rs — the certified Rust port (this module mirrors it line for line).
• entviz-js — the certified TypeScript/JavaScript port.

License

Apache License 2.0. See also NOTICE.

Documentation

Overview

Package entviz renders high-entropy values as comparable SVG fingerprints (entviz, spec v10). It is a Go port of the certified reference implementation; see https://github.com/dhh1128/entviz for the spec.

The deterministic shared core lives here: alphabets, tokenization + 24-bit quant extension, the SHA-512 fingerprint, ftok median/quartile selection, the Oklab color rules + weighted-RGB edge selection, and grid selection. The format-specific parsers live in entropy.go and the SVG renderer in pipeline.go.

Index

• Constants
• Variables
• func ClosestPaletteColor(target string, palette []string) string
• func ComputeFingerprint(core string) [64]byte
• func NucleusColors(quant uint32) (string, string)
• func OklabLightness(r, g, b uint8) float64
• func Render(entropyText string, targetAR, fontSizePt float64, note *string) (string, error)
• func SecondDigest(core string) [64]byte
• func WeightedRGBDistance(c1, c2 string) float64
• type Alphabet
• type Eip55Error
  • func (e *Eip55Error) Error() string
• type Grid
  • func ChooseGrid(tokenCount int, targetAR float64) Grid
• type Parsed
  • func Parse(entropy string) (*Parsed, error)
• type RenderError
  • func (e *RenderError) Error() string
• type Token
  • func MedianToken(tokens []Token) (Token, bool)
  • func QuartileTokens(tokens []Token) []*Token
  • func Tokenize(text string, alphabet Alphabet) []Token
  • func TokenizeEntropy(core string, alphabet Alphabet) ([]Token, bool)
  • func TokenizeFingerprint(digest [64]byte) []Token
• type VisualStyle
  • func SelectVisualStyle(medianFtok Token) VisualStyle

Constants

const LibVersion = "0.11.0"

LibVersion is this Go module's own version stamp. It is per-impl and is not compared by the conformance checker (only data-entviz-version is).

const SpecVersion = "v11"

SpecVersion is the entviz spec level this library implements.

Variables

var (
	HEX = Alphabet{
		Name:        "hex",
		Chars:       "0123456789ABCDEF",
		BitsPerChar: 4,
	}
	BASE64URL = Alphabet{
		Name:        "base64url",
		Chars:       "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_",
		BitsPerChar: 6,
	}
	BASE58 = Alphabet{
		Name:        "base58",
		Chars:       "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz",
		BitsPerChar: 6,
	}
	BASE64 = Alphabet{
		Name:        "base64",
		Chars:       "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
		BitsPerChar: 6,
	}
	BASE32 = Alphabet{
		Name:        "base32",
		Chars:       "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
		BitsPerChar: 5,
	}
	BECH32 = Alphabet{
		Name:        "bech32",
		Chars:       "qpzry9x8gf2tvdw0s3jn54khce6mua7l",
		BitsPerChar: 5,
	}
	CROCKFORD32 = Alphabet{
		Name:        "crockford32",
		Chars:       "0123456789ABCDEFGHJKMNPQRSTVWXYZ",
		BitsPerChar: 5,
	}
	BASE36 = Alphabet{
		Name:        "base36",
		Chars:       "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ",
		BitsPerChar: 6,
	}
	DECIMAL = Alphabet{
		Name:        "decimal",
		Chars:       "0123456789",
		BitsPerChar: 4,
	}
)

Canonical alphabet constants used across the core and parsers.

var MiddleDomainTag = []byte("entviz/fingerprint-middle/v6\x00")

MiddleDomainTag is the frozen domain-separation constant for the second digest. The trailing NUL is included; the v6 here is the *construction* version (frozen), NOT the spec version — see the spec's large-input section.

var PossibleEdgeColors = [5]string{"#ffffff", "#e7be00", "#ff3f2f", "#2f3fbf", "#000000"}

PossibleEdgeColors is the fixed palette; indices 0-3 are background candidates, black (index 4) is always an edge color.

Functions

func ClosestPaletteColor

func ClosestPaletteColor(target string, palette []string) string

ClosestPaletteColor returns the palette entry with minimum weighted distance.

func ComputeFingerprint

func ComputeFingerprint(core string) [64]byte

ComputeFingerprint returns the SHA-512 digest of the core text bytes.

func NucleusColors

func NucleusColors(quant uint32) (string, string)

NucleusColors returns (bgHex, fgHex). Red is the low byte of the quant.

func OklabLightness

func OklabLightness(r, g, b uint8) float64

OklabLightness returns the Oklab L of an sRGB color.

func Render

func Render(entropyText string, targetAR, fontSizePt float64, note *string) (string, error)

Render renders entropy as an entviz SVG string.

func SecondDigest

func SecondDigest(core string) [64]byte

SecondDigest returns SHA-512(MiddleDomainTag ‖ core). Computed for every input: it drives the two color-bar markers (and the middle cells on large inputs).

func WeightedRGBDistance

func WeightedRGBDistance(c1, c2 string) float64

WeightedRGBDistance is the spec's cheap CIELAB ΔE stand-in for edge selection.

Types

type Alphabet

type Alphabet struct {
	Name        string
	Chars       string
	BitsPerChar uint
}

Alphabet describes a character set and its tokenization density.

type Eip55Error

type Eip55Error struct {
	Position int
}

Eip55Error is a hard rejection: an EIP-55 mixed-case checksum mismatch. The Position is the 0-based index (within the 40-hex body) of the first digit whose case disagrees with the canonical case.

func (*Eip55Error) Error

func (e *Eip55Error) Error() string

type Grid

type Grid struct {
	Cols       int
	Rows       int
	TokenCount int
}

Grid is the chosen layout.

func ChooseGrid

func ChooseGrid(tokenCount int, targetAR float64) Grid

ChooseGrid selects the layout whose aspect ratio is closest to (but not below) the target, with at least 2 columns and 2 rows.

type Parsed

type Parsed struct {
	TypeName       string
	Alphabet       Alphabet
	Prefix         *string
	Core           string
	Suffix         *string
	PrefixSemantic bool
}

Parsed is a recognized entropy classification.

func Parse

func Parse(entropy string) (*Parsed, error)

Parse classifies the (already-trimmed) entropy string. It returns:

• (parsed, nil) on a recognized type or disproof-detected alphabet,
• (nil, nil) when nothing matches (caller re-encodes to base64url),
• (nil, err) on a hard rejection (EIP-55 checksum failure).

type RenderError

type RenderError struct {
	Kind     string // "note" | "input-too-long" | "font-size" | "aspect-ratio" | "no-tokens" | "eip55"
	Message  string
	Position int // for eip55
}

RenderError represents a render rejection. Kind discriminates the reason.

func (*RenderError) Error

func (e *RenderError) Error() string

type Token

type Token struct {
	Text  string
	Index int
	Quant uint32
}

Token is one rendered chunk of entropy (or one ftok of a fingerprint).

func MedianToken

func MedianToken(tokens []Token) (Token, bool)

MedianToken returns the lower-middle token of the ASCII text-sorted list.

func QuartileTokens

func QuartileTokens(tokens []Token) []*Token

QuartileTokens returns the first token of each of the four mirror-sorted quartiles; a slot is absent (ok=false) when it would fall in padding.

func Tokenize

func Tokenize(text string, alphabet Alphabet) []Token

Tokenize splits text into 24-bit tokens under the given alphabet, extending short trailing chunks to a full 24-bit quant by the bit-repeat rule.

func TokenizeEntropy

func TokenizeEntropy(core string, alphabet Alphabet) ([]Token, bool)

TokenizeEntropy tokenizes entropy with v6+ large-input handling. It returns (tokens, truncated).

func TokenizeFingerprint

func TokenizeFingerprint(digest [64]byte) []Token

TokenizeFingerprint serializes the 64-byte digest to base64url and splits it into the 22 ftoks the spec guarantees.

type VisualStyle

type VisualStyle struct {
	BgColor    string
	EdgeColors []string
}

VisualStyle is the entviz background plus the 4-entry edge palette.

func SelectVisualStyle

func SelectVisualStyle(medianFtok Token) VisualStyle

SelectVisualStyle picks the background from the median ftok's low 2 bits and forms the edge palette from the remaining four colors.