dataset

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package dataset is the versioned JSONL codec for eval scenarios. It is the eval framework's untrusted deserialization boundary: a dataset file is one dataset/v1 envelope per line, each carrying an explicit version discriminator and a scenario payload. The codec reads the version first and rejects unknown or missing versions before trusting the payload (fail-closed), reconstructs the conversation by discriminating each message's role, and validates every scenario against the strict eval domain types before returning it.

All sizes are bounded (MaxRecordBytes per line, MaxFileBytes per file), records load and are returned in file order, duplicate scenario IDs are rejected, and every failure is a typed error carrying only safe locators (a caller-supplied file name and a 1-based line number) — never the offending record bytes, conversation text, or tool output. Directory-scoped loading uses os.Root so a symlink or "../" in a file name cannot escape the caller-provided root.

Index

Constants

View Source 
const (
	// MaxRecordBytes bounds a single JSONL record (one line).
	MaxRecordBytes = 1 << 20 // 1 MiB
	// MaxFileBytes bounds a whole dataset file.
	MaxFileBytes = 16 << 20 // 16 MiB
)

Byte bounds for the untrusted decode boundary. They reject an oversized line or file before it can exhaust memory. Conservative starting values; tune to real dataset sizes later.

Variables

This section is empty.

Functions

func DecodeRecord 

func DecodeRecord(data []byte) (eval.Scenario, error)

DecodeRecord decodes a single JSONL record into a validated scenario. It is the untrusted boundary and the fuzz target: for any input it returns either a valid scenario or a typed error, and never panics. Enforced in order: the per-record size bound, valid UTF-8, exactly one JSON value (no trailing data), a known version, a reconstructable conversation, and domain validation.

func Encode 

func Encode(w io.Writer, scenarios []eval.Scenario) error

Encode writes each scenario as one JSONL record terminated by a newline, in order. It rejects duplicate scenario IDs so an encoded dataset never decodes into a duplicate.

func EncodeRecord 

func EncodeRecord(sc eval.Scenario) ([]byte, error)

EncodeRecord serializes a scenario to a single JSONL record (no trailing newline). It validates the scenario first, so only well-formed records are emitted, and enforces the per-record size bound on the result.

Types

type Dataset 

type Dataset struct {
	Scenarios []eval.Scenario
}

Dataset is an ordered set of validated scenarios decoded from a dataset file. Order mirrors file order, so a dataset is reproducible.

func Decode 

func Decode(ctx context.Context, r io.Reader, name string) (*Dataset, error)

Decode reads a JSONL dataset from r and returns its scenarios in file order. name is a safe locator used only in diagnostics. Decode enforces the file and per-record size bounds, requires each non-terminal line to be exactly one JSON value, and rejects duplicate scenario IDs.

func Load 

func Load(ctx context.Context, dir, name string) (*Dataset, error)

Load opens name under dir using an os.Root, so a symlink or "../" in name cannot escape dir, and decodes the file. dir and name are caller-supplied and treated as safe locators. A name that resolves outside the root is refused with a *PathEscapeError.

type DirectoryError 

type DirectoryError struct {
	Dir   string
	Cause error
}

DirectoryError reports that the dataset root directory itself could not be opened. Dir is the caller-supplied (safe) directory; Cause is exposed via Unwrap.

func (*DirectoryError) Error 

func (e *DirectoryError) Error() string

func (*DirectoryError) Unwrap 

func (e *DirectoryError) Unwrap() error

type DuplicateScenarioError 

type DuplicateScenarioError struct {
	// Line is the 1-based line of the duplicate.
	Line int
	// FirstLine is the 1-based line where the ID was first seen.
	FirstLine int
}

DuplicateScenarioError reports that two records carried the same scenario ID, which would make two cases indistinguishable in a report and in baseline comparison. The offending ID is caller-supplied and withheld; only the safe line numbers are reported.

func (*DuplicateScenarioError) Error 

func (e *DuplicateScenarioError) Error() string

type EncodeError 

type EncodeError struct {
	Cause error
}

EncodeError reports that a scenario could not be serialized to a record. Cause is exposed via Unwrap. It is a programming/input error on the encode side, not a decode-boundary failure.

func (*EncodeError) Error 

func (e *EncodeError) Error() string

func (*EncodeError) Unwrap 

func (e *EncodeError) Unwrap() error

type FileTooLargeError 

type FileTooLargeError struct {
	Path string
	Max  int
}

FileTooLargeError reports that a dataset file exceeded MaxFileBytes. Path is the caller-supplied (safe) file name.

func (*FileTooLargeError) Error 

func (e *FileTooLargeError) Error() string

type InvalidScenarioError 

type InvalidScenarioError struct {
	Line  int
	Cause error
}

InvalidScenarioError reports that a decoded record was well-formed JSON but the reconstructed scenario failed domain validation. Cause is the eval package's own typed validation error — itself free of untrusted content — and is exposed via Unwrap so callers can classify it (for example errors.As to *eval.ValidationError).

func (*InvalidScenarioError) Error 

func (e *InvalidScenarioError) Error() string

func (*InvalidScenarioError) Unwrap 

func (e *InvalidScenarioError) Unwrap() error

type MalformedRecordError 

type MalformedRecordError struct {
	Line   int
	Reason string
}

MalformedRecordError reports that a record was not exactly one well-formed JSON value, or that its conversation could not be reconstructed. Reason is drawn only from the fixed vocabulary above, so no untrusted content leaks.

func (*MalformedRecordError) Error 

func (e *MalformedRecordError) Error() string

type OpenError 

type OpenError struct {
	Path  string
	Cause error
}

OpenError reports that a file under the root could not be opened for a reason other than a root escape (it does not exist, or permission was denied). Path is the caller-supplied (safe) name; Cause is exposed via Unwrap.

func (*OpenError) Error 

func (e *OpenError) Error() string

func (*OpenError) Unwrap 

func (e *OpenError) Unwrap() error

type PathEscapeError 

type PathEscapeError struct {
	Path  string
	Cause error
}

PathEscapeError reports that a file name resolved outside the caller-provided root directory — for example via a symlink or a "../" traversal — and was refused by the os.Root-scoped loader. Path is the caller-supplied (safe) name; Cause is the underlying os error, exposed via Unwrap but never rendered.

func (*PathEscapeError) Error 

func (e *PathEscapeError) Error() string

func (*PathEscapeError) Unwrap 

func (e *PathEscapeError) Unwrap() error

type ReadError 

type ReadError struct {
	Path  string
	Cause error
}

ReadError reports that reading the dataset file failed partway through. Path is the caller-supplied (safe) name; Cause is exposed via Unwrap.

func (*ReadError) Error 

func (e *ReadError) Error() string

func (*ReadError) Unwrap 

func (e *ReadError) Unwrap() error

type RecordTooLargeError 

type RecordTooLargeError struct {
	Line int
	Size int
	Max  int
}

RecordTooLargeError reports that a single record exceeded MaxRecordBytes. Only safe integers are carried; no record content is embedded.

func (*RecordTooLargeError) Error 

func (e *RecordTooLargeError) Error() string

type UnknownVersionError 

type UnknownVersionError struct {
	// Line is the 1-based record line, or 0 when decoded standalone.
	Line int
	// Version is a bounded, safe rendering of the offending token, or "" when
	// it was missing or withheld.
	Version string
}

UnknownVersionError reports that a record's version discriminator was missing or names a wire version this codec does not implement. The version token may originate from untrusted input, so it is bounded and withheld when hostile; Version is either a short, valid token or "" when redacted.

func (*UnknownVersionError) Error 

func (e *UnknownVersionError) Error() string

type WriteError 

type WriteError struct {
	Cause error
}

WriteError reports that writing an encoded record to the output stream failed. Cause is exposed via Unwrap.

func (*WriteError) Error 

func (e *WriteError) Error() string

func (*WriteError) Unwrap 

func (e *WriteError) Unwrap() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.