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 ¶
- func AddEncodeSeeds(f *testing.F)
- func AddScanSeeds(f *testing.F)
- func CheckArgs(t Reporter, ...)
- func CheckChord(t Reporter, diff func(before, after []byte) ([]byte, error))
- func CheckEncode(t Reporter, encode func(in []byte) ([]byte, error))
- func CheckScan(t Reporter, scan func(record []byte) (Index, error))
- func CheckUUID(t Reporter, ...)
- func EncodeFuzz(encode func(in []byte) ([]byte, error)) func(*testing.T, []byte)
- func ReferenceEncode(in []byte) ([]byte, error)
- func ScanFuzz(scan func(record []byte) (Index, error)) func(*testing.T, []byte)
- func Summary(tb Reporter) string
- type ArgsVector
- type ChordVector
- type EncodeVector
- type Index
- type Line
- type MemoryLog
- type Param
- type Reporter
- type ScanVector
- type Stmt
- type UUIDCall
- type UUIDVector
- type Writer
- func (w *Writer) Close(code int) error
- func (w *Writer) Commit(store string, seq int64, stmts []Stmt) error
- func (w *Writer) Meta(scenario, impl string) error
- func (w *Writer) Model(call int, bench string) error
- func (w *Writer) Out(text string) error
- func (w *Writer) Store(label, path string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddEncodeSeeds ¶
AddEncodeSeeds adds the encoder vectors' inputs as seeds.
func AddScanSeeds ¶
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 ¶
CheckChord runs every Chord vector: diff returns the ops as JSON text.
func CheckEncode ¶
CheckEncode runs every encoder vector: encode reads JSON text and writes what JSON.stringify writes for the parsed value.
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 ¶
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 ¶
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.
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 ¶
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 ¶
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).
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.
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 ¶
OpenMemoryLog opens the log at path; an empty path yields a nil log.
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 ¶
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 UUIDCall ¶
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 ¶
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 ¶
NewWriter creates the trace file. The crash switch is read from CONTRACT_CRASH_AFTER, the variable the Node tools set.
func (*Writer) Commit ¶
Commit records one committed transaction. Call it after the commit succeeded in the store; it then honours the crash switch.
func (*Writer) Model ¶
Model records a model call's bench fingerprint (a native core that does not build the full pi-ai Context writes only this).
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. |