contracttest

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package contracttest is the Go side of the Durable core conformance gate (docs/plan/durable-core/CONTRACT.md sections 5-7).

The Node tooling in durable/contract captures pi-durable and compares implementations at the store, commit, context and output levels. This package supplies what a Go core needs from that gate:

  • the byte-level differential vectors of CONTRACT 5.6, generated from the reference's own code (durable/contract/tools/gen-oracle.mjs) and embedded here: encoder, scanner, Chord ops, tool-argument validation and uuidv7. The Check* functions run one vector family against a function the core under test supplies, so this package imports nothing from the core and the core's tests can import this package;
  • ReferenceEncode, ReferenceIndex and the fuzz kit (AddEncodeSeeds, EncodeFuzz, AddScanSeeds, ScanFuzz): Go models of the reference's JSON.stringify(JSON.parse(x)) and entry-record extraction, proved against the vectors, so a core fuzzes its encoder and scanner against an oracle with unlimited inputs;
  • Writer and ReadTrace: the trace format (JSON Lines, CONTRACT 7.6) of a native run, statements only, and the crash switch (CONTRACT_CRASH_AFTER) the Node gate sets; cmd/replayhost is a script-driven host that proves the native path.

Fuzz runs are bounded: GOMAXPROCS=8 go test -fuzz=<name> -parallel=4 -fuzztime=30s.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddEncodeSeeds

func AddEncodeSeeds(f *testing.F)

AddEncodeSeeds adds the encoder vectors' inputs as seeds.

func AddScanSeeds

func AddScanSeeds(f *testing.F)

AddScanSeeds adds the scanner vectors' records as seeds.

func CheckArgs

func CheckArgs(t Reporter, validate func(tool []byte, plainSchema bool, name string, arguments []byte) (ok []byte, errMessage string))

CheckArgs runs every vector: validate returns the arguments JSON, or a non-empty message when validation fails.

func CheckChord

func CheckChord(t Reporter, diff func(before, after []byte) ([]byte, error))

CheckChord runs every Chord vector: diff returns the ops as JSON text.

func CheckEncode

func CheckEncode(t Reporter, encode func(in []byte) ([]byte, error))

CheckEncode runs every encoder vector: encode reads JSON text and writes what JSON.stringify writes for the parsed value.

func CheckScan

func CheckScan(t Reporter, scan func(record []byte) (Index, error))

CheckScan runs every scanner vector.

func CheckUUID

func CheckUUID(t Reporter, newGenerator func(now func() int64, random func(dst []byte)) func(ts *int64) string)

CheckUUID runs every uuidv7 vector. newGenerator returns a fresh process-level generator over a clock and a random source; the generator takes the optional explicit timestamp.

func EncodeFuzz

func EncodeFuzz(encode func(in []byte) ([]byte, error)) func(*testing.T, []byte)

EncodeFuzz returns a fuzz body: for any input that is JSON text, encode must write exactly what ReferenceEncode writes. Input that is not JSON is skipped: the core encodes what it wrote or what a host passed it, never arbitrary bytes.

func ReferenceEncode

func ReferenceEncode(in []byte) ([]byte, error)

ReferenceEncode is a Go model of JSON.stringify(JSON.parse(in)) for the JSON the core writes (CONTRACT 3.1, 5.6). It exists so a core's encoder can be fuzzed against an oracle with unlimited inputs; the vectors in testdata/oracle/encode.jsonl, produced by the reference runtime, prove the model (TestReferenceEncodeReproducesEveryEncodeVector). It is test tooling: it uses the standard library freely and is not part of the core.

What it models: object properties in JavaScript order (array-index keys ascending first, then the others in first-insertion order, a repeated key keeping its first position and its last value), numbers as Number.prototype.toString prints them (-0 is 0, a value beyond the double range is null), strings with JSON.stringify's escapes and lone surrogates written as \udxxx.

func ScanFuzz

func ScanFuzz(scan func(record []byte) (Index, error)) func(*testing.T, []byte)

ScanFuzz returns a fuzz body: for any record a JSON decoder reads into an index, scan must return the same index. Records that are not valid UTF-8 or whose strings hold a replacement character (a lone surrogate escape, which a Go decoder cannot keep) are skipped.

func Summary

func Summary(tb Reporter) string

Summary counts the vectors of each family, for reports.

Types

type ArgsVector

type ArgsVector struct {
	Tool        json.RawMessage `json:"tool"`
	PlainSchema bool            `json:"plainSchema"`
	Call        struct {
		Name      string          `json:"name"`
		Arguments json.RawMessage `json:"arguments"`
	} `json:"call"`
	OK    *string `json:"ok"`
	Error *string `json:"error"`
}

ArgsVector is pi-ai validateToolArguments(Tool, Call): the converted arguments as JSON text (OK, key order included, which coerceWithJsonSchema can change), or the error message text. PlainSchema means Tool.parameters is a plain JSON schema, not a TypeBox schema, which selects the coercion path that reassigns keys.

func ArgsVectors

func ArgsVectors(tb Reporter) []ArgsVector

ArgsVectors returns the tool-argument vectors.

type ChordVector

type ChordVector struct {
	Before json.RawMessage `json:"before"`
	After  json.RawMessage `json:"after"`
	Ops    json.RawMessage `json:"ops"`
}

ChordVector is a document before and after an edit and the ops @earendil-works/chord's diffRevisions returns, as the compact JSON text JSON.stringify writes (Chord Op tuples: `r`, `s`, `d`, `a`, `t`, ...).

func ChordVectors

func ChordVectors(tb Reporter) []ChordVector

ChordVectors returns the Chord vectors.

type EncodeVector

type EncodeVector struct {
	In  string `json:"in"`
	Out string `json:"out"`
}

EncodeVector is JSON text and the bytes JSON.stringify(JSON.parse(In)) produces: insertion order (integer-like keys first, ascending), ECMAScript number formatting, only `"`, `\` and C0 controls escaped, lone surrogates as \udXXX.

func EncodeVectors

func EncodeVectors(tb Reporter) []EncodeVector

EncodeVectors returns the encoder vectors.

type Index

type Index struct {
	Kind           string `json:"kind"`
	ID             int64  `json:"id"`
	ConversationID int64  `json:"conversationId"`
	Head           *int64 `json:"head"`
	Role           string `json:"role"`
	StopReason     string `json:"stopReason"`
	Messages       int    `json:"messages"`
}

Index is what a JSON.parse-based extraction reads from an entry record; the scanner must produce the same without decoding. Head is nil when the record has no `head`; Role and StopReason are empty when the first model message lacks them.

func ReferenceIndex

func ReferenceIndex(record []byte) (Index, error)

ReferenceIndex reads an entry record with a JSON decoder: what the core's scanner must produce without decoding. It rejects what the decoder rejects (invalid JSON, a number that is not an integer id).

func (Index) Equal

func (a Index) Equal(b Index) bool

Equal compares every field, Head by value.

type Line

type Line struct {
	T      string
	Fields map[string]json.RawMessage
}

Line is one trace line, kept as the raw fields so unknown line types survive.

func ReadTrace

func ReadTrace(path string) ([]Line, error)

ReadTrace reads a trace file.

type MemoryLog

type MemoryLog struct {
	// contains filtered or unexported fields
}

MemoryLog appends one resident-memory sample per measured turn to the file the gate names in CONTRACT_MEM, as {"turn":N,"rss":BYTES} lines. The gate bounds the growth per turn (durable/contract/lib/memory.mjs): a candidate that allocates without bound fails its row with the numbers instead of trapping or being killed later. A nil *MemoryLog records nothing.

func OpenMemoryLog

func OpenMemoryLog(path string) (*MemoryLog, error)

OpenMemoryLog opens the log at path; an empty path yields a nil log.

func (*MemoryLog) Close

func (m *MemoryLog) Close()

Close closes the log.

func (*MemoryLog) Sample

func (m *MemoryLog) Sample(turn int)

Sample records the process's resident set after a turn. It returns freed memory to the OS first, so the sample is what the run retains rather than what the collector has not yet released.

type Param

type Param any

Param is one bound statement parameter: nil, int64, float64, string or []byte.

func DecodeParams

func DecodeParams(raw json.RawMessage) ([]Param, error)

DecodeParams reads the `p` array of a statement from a trace or a script: integers are int64, other numbers float64, a {"blob": hex} object is []byte. A host that binds parameters must keep the integer/real distinction (SQLite STRICT tables).

type Reporter

type Reporter interface {
	Helper()
	Errorf(format string, args ...any)
	Fatalf(format string, args ...any)
}

Reporter is what the vector functions need of a test: *testing.T or testing.TB, or a recorder when a test proves a check fails on a broken implementation.

type ScanVector

type ScanVector struct {
	Record string
	Index  Index
}

ScanVector is an entry record (any key order, unknown fields, escaped keys, nested look-alike keys) and its index.

func ScanVectors

func ScanVectors(tb Reporter) []ScanVector

ScanVectors returns the scanner vectors.

type Stmt

type Stmt struct {
	SQL    string
	Params []Param
}

Stmt is one statement of a commit with its bound parameters.

type UUIDCall

type UUIDCall struct {
	Now    int64  `json:"now"`
	Ts     *int64 `json:"ts"`
	Random string `json:"random"`
}

UUIDCall is one uuidv7() call: the clock reads Now, crypto.getRandomValues fills Random (32 hex digits) and Ts, when present, is the explicit timestamp argument (a follower id; it bypasses the process-wide monotonic timestamp).

type UUIDVector

type UUIDVector struct {
	Calls []UUIDCall `json:"calls"`
	Out   []string   `json:"out"`
}

UUIDVector is a sequence of calls in one process; the generator's sequence counter and last timestamp carry across calls.

func UUIDVectors

func UUIDVectors(tb Reporter) []UUIDVector

UUIDVectors returns the uuidv7 vectors.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer writes the trace format of CONTRACT section 7.6 (JSON Lines) for a native run. It records each commit's statements only; durable/contract/lib/replay.mjs derives the row changes by replaying them onto the store the run started from. Lines are written when called, so a process killed after a commit has already written every line up to it.

func NewWriter

func NewWriter(path string) (*Writer, error)

NewWriter creates the trace file. The crash switch is read from CONTRACT_CRASH_AFTER, the variable the Node tools set.

func (*Writer) Close

func (w *Writer) Close(code int) error

Close writes the end line and closes the file.

func (*Writer) Commit

func (w *Writer) Commit(store string, seq int64, stmts []Stmt) error

Commit records one committed transaction. Call it after the commit succeeded in the store; it then honours the crash switch.

func (*Writer) Meta

func (w *Writer) Meta(scenario, impl string) error

Meta writes the first line.

func (*Writer) Model

func (w *Writer) Model(call int, bench string) error

Model records a model call's bench fingerprint (a native core that does not build the full pi-ai Context writes only this).

func (*Writer) Out

func (w *Writer) Out(text string) error

Out records one line of the scenario's output.

func (*Writer) Store

func (w *Writer) Store(label, path string) error

Store names the store a run opened.

Directories

Path Synopsis
Package boundary checks that the production core links none of the reflection-driven standard-library packages TinyGo cannot build faithfully (go list -deps over the core packages, the Go and the Wasm configuration).
Package boundary checks that the production core links none of the reflection-driven standard-library packages TinyGo cannot build faithfully (go list -deps over the core packages, the Go and the Wasm configuration).
cmd
benchhost command
Command benchhost runs the durable-bench scenario (CONTRACT section 6: W1, W2, W4c, X1 and the H handoff rows) on the production Durable core packages as a native bench host.
Command benchhost runs the durable-bench scenario (CONTRACT section 6: W1, W2, W4c, X1 and the H handoff rows) on the production Durable core packages as a native bench host.
countgate command
Command countgate measures what the Durable core costs on a recorded workload (package counts): bytes allocated, mallocs, Wasm instructions on an instrumented module, native instructions under callgrind, and the growth of the live set per turn.
Command countgate measures what the Durable core costs on a recorded workload (package counts): bytes allocated, mallocs, Wasm instructions on an instrumented module, native instructions under callgrind, and the growth of the live set per turn.
replayhost command
Command replayhost is a script-driven stand-in for a native Durable core host: it applies the statements of a recorded trace to a SQLite store, one transaction per commit, and writes its own trace with contracttest.Writer.
Command replayhost is a script-driven stand-in for a native Durable core host: it applies the statements of a recorded trace to a SQLite store, one transaction per commit, and writes its own trace with contracttest.Writer.
scprovider command
Command scprovider serves the core's write encoder to the storage conformance suite (CONTRACT 3.10, the SC row): the suite's Storage is pi-durable's SqliteStorage for every read, and this process for commit and mintId.
Command scprovider serves the core's write encoder to the storage conformance suite (CONTRACT 3.10, the SC row): the suite's Storage is pi-durable's SqliteStorage for every read, and this process for commit and mintId.
Package counts is the Durable core's deterministic count gate (Durable plan 2, item 9) and its flight recorder format.
Package counts is the Durable core's deterministic count gate (Durable plan 2, item 9) and its flight recorder format.
Package fuel meters a WebAssembly module: Instrument rewrites a module so that every basic block adds its own length to a counter, the Wasm instruction count the count gate ratchets (docs/plan/durable-core, Durable plan 2 item 9).
Package fuel meters a WebAssembly module: Instrument rewrites a module so that every basic block adds its own length to a counter, the Wasm instruction count the count gate ratchets (docs/plan/durable-core, Durable plan 2 item 9).
Package guard bounds a native host process of the conformance gate: a request that runs too long, a heap that grows past a limit, or a parent that has gone.
Package guard bounds a native host process of the conformance gate: a request that runs too long, a heap that grows past a limit, or a parent that has gone.
Package storehost is the synchronous SQLite host of ABI section 3 for the store alone: tooling that drives store.Store (the benchmark engine, the storage-conformance provider) applies a step's commits and answers its reads with it.
Package storehost is the synchronous SQLite host of ABI section 3 for the store alone: tooling that drives store.Store (the benchmark engine, the storage-conformance provider) applies a step's commits and answers its reads with it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL