codegen

type Field struct {
	// Name is the Go-visible field name (e.g. "Time"). Emitted into
	// the schema's Fields struct as `<SchemaGoName>Fields.Name`.
	Name string
	// Type is the Go type as a string. Supported: scalar FieldKind
	// types, "bytes<N>" for fixed byte arrays, or "string"/"bytes" for
	// variable-length tails.
	Type string
	// Offset is the byte position within the fixed-size payload. For
	// variable-length fields this is where the 8-byte tail pointer sits.
	Offset uint32
	// Elem, when non-nil, marks this field as a variable-length LIST of a
	// fixed-size element schema (Type is ignored for list fields). The
	// field occupies an 8-byte list pointer {relOffset, length} at Offset;
	// the elements live in the object tail and are read via [zapv1.ListAt].
	Elem *ListElem
	// Nested, when non-nil, marks this field as a SINGULAR nested object
	// (Type is ignored). The field occupies a 4-byte object pointer
	// {relOffset} at Offset; the nested object lives in the object tail and
	// is read via [zapv1.NestedAt]. The proto3 "message field" case — the
	// singular peer of Elem. An unset value (nil) encodes as a null pointer.
	Nested *NestedMsg
}

type ListElem struct {
	// Schema is the element schema's marker GoName, e.g. "ItemSchema".
	// Emitted as the List[E] / WriteList[S,E] / ListAt[S,E] type param.
	Schema string
	// Wire is the element schema's WireName, e.g. "BatchItem". Needed to
	// reference the element's variable-length Offset<Wire>_<Field>
	// constants when an element carries string/bytes sub-fields. May be
	// empty for scalar-only elements (which use only <Schema>Fields).
	Wire string
	// Value is the Go value-struct the constructor accepts per element,
	// e.g. "Item". Emitted as `type Value struct { ...Fields... }` and the
	// list parameter is `[]Value`.
	Value string
	// Stride is the element's fixed payload size in bytes (its Size()).
	Stride int
	// Fields are the element's fields, in order (scalar, string, bytes).
	// Used to emit the Value struct and the per-element WriteList body
	// (one write per field, from the value struct into the element Setter).
	Fields []Field
}

type NestedMsg struct {
	// Schema is the nested schema's marker GoName, e.g. "InnerSchema".
	// Emitted as the View[N] / WriteNested[S,N] / NestedAt[S,N] type param.
	Schema string
	// Wire is the nested schema's WireName, e.g. "Inner". Referenced for
	// the nested's Offset<Wire>_<Field> constants when it carries
	// string/bytes sub-fields.
	Wire string
	// Value is the Go value-struct the constructor accepts (by POINTER, so
	// nil encodes the unset/null case), e.g. "Inner". Emitted as
	// `type Value struct { ...Fields... }`; the parameter is `*Value`.
	Value string
	// Fields are the nested object's fields, in order. Used to emit the
	// Value struct and the WriteNested body (one write per field).
	Fields []Field
}

type Schema struct {
	// GoName is the Go type name for the schema marker struct (e.g.
	// "AdvanceTimeSchema"). Used as the View[S] type parameter.
	GoName string
	// WireName is the human-readable name of the schema (e.g.
	// "AdvanceTimeTx"). Used in error messages and Registry lookup.
	// Stable across versions — part of the schema's identity.
	WireName string
	// Kind is the discriminator byte at object offset 0.
	Kind uint8
	// Size is the fixed object payload in bytes (excluding header).
	Size int
	// Package is the Go package the emitted file should live in.
	Package string
	// Fields is the ordered list of fields: scalars, fixed byte arrays
	// ("bytes<N>"), and variable-length tails ("string"/"bytes"). Each
	// occupies a slot in the fixed payload (variable-length fields hold
	// an 8-byte tail pointer there). List and nested-object tails are
	// not declared here; they use the generic [zapv1.ListAt] machinery.
	Fields []Field
	// SkipRegistry suppresses the emit of `init() { zapv1.Register[S]
	// (zapv1.DefaultRegistry) }`. Use for schema families that have a
	// PRIVATE Kind namespace (the discriminator byte is unique only
	// within a per-package registry, not globally). Examples:
	//
	//  - LP-186 chains-VM wire: each <vm>wire package has its own
	//    KindBlock=0x01 / KindTx=0x02 / etc. Registering all twelve
	//    KindBlock=0x01 implementations into a single global registry
	//    would panic on duplicate kind byte at init time.
	//  - LP-182 consensus wire: the 0x01..0x0D kind bytes are local to
	//    the consensus-wire registry (`pkg/wire/zap/schemas.go`), not
	//    the global zapv1.DefaultRegistry shared with P2P/light-client
	//    schemas at 0xD0+/0xF0+.
	//
	// Default is false — schemas with globally-unique Kind bytes
	// (LP-201, LP-208, LP-211, LP-214, LP-218) DO register at init.
	SkipRegistry bool
	// Element marks this schema as a LIST ELEMENT: a flat, fixed-size
	// value slot with NO kind discriminator byte at offset 0 (fields may
	// start at offset 0), built inline by a parent's [zapv1.WriteList] and
	// read via [zapv1.List][E].At — never wrapped as a top-level message.
	// The Kind()/Size()/Name() methods are still emitted (List[E] and the
	// registry need the Schema interface), but Kind is NOT stored in the
	// slot and Wrap does not validate it. Default false (top-level kinded
	// message: offset 0 reserved for the discriminator).
	Element bool
}