slidge-whatsapp 0.2.6__cp313-cp313-manylinux_2_36_aarch64.whl → 0.3.0__cp313-cp313-manylinux_2_36_aarch64.whl

slidge_whatsapp/vendor/github.com/beeper/argo-go/codec/encoder.go

@@ -0,0 +1,985 @@
+package codec
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"math"
+	"math/big"
+	"os"
+	"reflect"
+	"sort"
+
+	"github.com/beeper/argo-go/block"
+	"github.com/beeper/argo-go/header"
+	"github.com/beeper/argo-go/internal/util"
+	"github.com/beeper/argo-go/label"
+	"github.com/beeper/argo-go/pkg/buf"
+	"github.com/beeper/argo-go/pkg/varint"
+	"github.com/beeper/argo-go/wire"
+	"github.com/elliotchance/orderedmap/v3"
+	"github.com/vektah/gqlparser/v2/ast"
+)
+
+// writerEntry stores an association between a block.AnyBlockWriter and the
+// original wire.Type of the values it's intended to write. This is important for
+// type-specific operations, such as determining if null termination is needed for string blocks.
+type writerEntry struct {
+	Writer            block.AnyBlockWriter // The type-erased block writer instance.
+	OriginalValueType wire.Type            // The original wire type this writer was created for (e.g., wire.String, wire.Bytes).
+}
+
+// ArgoEncoder handles the conversion of Go data structures, typically representing
+// GraphQL query results, into the Argo binary message format. It manages a core
+// buffer for labels and inline data, a collection of block writers for scalar
+// values that are not inlined, and an Argo header.
+// The encoder supports various Argo features like deduplication, different block types,
+// and self-describing values, controlled by header flags and wire type definitions.
+type ArgoEncoder struct {
+	coreBuf *buf.Buf // Buffer for the core message data, primarily labels and inlined scalar values.
+	// writers stores block writers, keyed by their wire.BlockKey. Each entry contains the
+	// AnyBlockWriter and the original wire.Type for which it was created.
+	writers *orderedmap.OrderedMap[wire.BlockKey, writerEntry]
+	header  *header.Header // The Argo header for the message being encoded.
+
+	// Debug fields, used when ArgoEncoder.Debug is true.
+	Debug bool // If true, enables tracking of encoding steps.
+	// tracked stores a log of encoding operations when Debug is true.
+	// Each entry is an ordered map representing a single tracked step.
+	tracked []*orderedmap.OrderedMap[string, interface{}]
+}
+
+// NewArgoEncoder initializes and returns a new ArgoEncoder.
+// It sets up the core buffer, the map for block writers, and a new Argo header.
+func NewArgoEncoder() *ArgoEncoder {
+	// Initial capacity for coreBuf; it will grow as needed.
+	// The final message buffer is constructed in GetResult by combining the header,
+	// block data (if not inlined), and the core buffer contents.
+	coreBuffer := buf.NewBuf(1024) // Default initial capacity.
+	hdr := header.NewHeader()
+
+	return &ArgoEncoder{
+		coreBuf: coreBuffer,
+		writers: orderedmap.NewOrderedMap[wire.BlockKey, writerEntry](),
+		header:  hdr,
+		tracked: []*orderedmap.OrderedMap[string, interface{}]{}, // Initialize an empty slice for tracking.
+	}
+}
+
+// Header returns the encoder's *header.Header instance, allowing the caller
+// to set Argo header flags or other header properties before finalizing the message.
+func (ae *ArgoEncoder) Header() *header.Header {
+	return ae.header
+}
+
+// Track records an encoding step for debugging purposes if ae.Debug is true.
+// It captures the GraphQL path, a descriptive message, the current buffer (if any),
+// and the value being processed.
+func (ae *ArgoEncoder) Track(path ast.Path, msg string, b buf.Write, value interface{}) {
+	if ae.Debug {
+		entry := orderedmap.NewOrderedMap[string, interface{}]()
+		entry.Set("path", util.FormatPath(path))
+		entry.Set("msg", msg)
+		if b != nil { // Buffer might be nil for some tracking events (e.g., header bytes)
+			entry.Set("pos", b.Position())
+		} else {
+			entry.Set("pos", -1) // Indicate no buffer position
+		}
+
+		// Avoid deep copying complex values or handle them carefully
+		if s, ok := value.(string); ok && len(s) > 100 {
+			entry.Set("value", s[:100]+"...")
+		} else if b, ok := value.([]byte); ok && len(b) > 100 {
+			entry.Set("value", fmt.Sprintf("bytes[%d]", len(b)))
+		} else {
+			entry.Set("value", value)
+		}
+		ae.tracked = append(ae.tracked, entry)
+	}
+}
+
+// Log provides a more generic logging mechanism for debugging, used when ae.Debug is true.
+// It records the current position in the core buffer and a message or detailed object.
+func (ae *ArgoEncoder) Log(msg interface{}) {
+	if ae.Debug {
+		entry := orderedmap.NewOrderedMap[string, interface{}]()
+		entry.Set("pos", ae.coreBuf.Position())
+
+		if s, ok := msg.(string); ok {
+			entry.Set("msg", s)
+		} else if om, ok := msg.(*orderedmap.OrderedMap[string, interface{}]); ok {
+			// If msg is an OrderedMap, merge its fields.
+			for el := om.Front(); el != nil; el = el.Next() {
+				entry.Set(el.Key, el.Value)
+			}
+		} else {
+			entry.Set("detail", msg)
+		}
+		ae.tracked = append(ae.tracked, entry)
+	}
+}
+
+// nullTerminator is a pre-allocated byte slice for null-terminating strings.
+var nullTerminator = []byte{0x00}
+
+// makeBlockWriter creates and returns a block.AnyBlockWriter suitable for the given wire.Type `t`
+// and deduplication setting. It handles various scalar types by configuring appropriate
+// ValueToBytesFunc and MakeLabelFunc for the underlying block.BlockWriter or
+// block.DeduplicatingBlockWriter.
+// For BytesType with deduplication, it uses a specialized bytesDeduplicatingAdapter.
+func (ae *ArgoEncoder) makeBlockWriter(t wire.Type, dedupe bool) (block.AnyBlockWriter, error) {
+	switch t.(type) {
+	case wire.StringType:
+		stringVTB := func(s string) ([]byte, error) { // ValueToBytesFunc for string
+			return []byte(s), nil
+		}
+		if dedupe {
+			// For strings, deduplication uses the string itself as the key.
+			dbw := block.NewLengthOfBytesDeduplicatingBlockWriter[string](stringVTB)
+			return block.NewAnyDeduplicatingBlockWriter(dbw), nil
+		}
+		// Non-deduplicating string writer also uses length-based labels.
+		bw := block.NewLengthOfBytesBlockWriter[string](stringVTB)
+		return block.NewAnyBlockWriter(bw), nil
+
+	case wire.BytesType:
+		bytesVTB := func(b []byte) ([]byte, error) { // ValueToBytesFunc for []byte
+			return b, nil
+		}
+		if dedupe {
+			// For BytesType with deduplication, the underlying DeduplicatingBlockWriter[string]
+			// uses string(originalBytes) as the deduplication key.
+			// The bytesDeduplicatingAdapter handles the conversion from []byte input (in its Write method)
+			// to the string key expected by the core writer.
+			dedupeKeyedVTB := func(sKey string) ([]byte, error) { // ValueToBytes for the string-keyed deduplicator
+				return []byte(sKey), nil
+			}
+			dbw := block.NewLengthOfBytesDeduplicatingBlockWriter[string](dedupeKeyedVTB)
+			return &bytesDeduplicatingAdapter{dbw}, nil // Specialized adapter for []byte with string-keyed dedupe.
+		}
+		// Non-deduplicating bytes writer.
+		bw := block.NewLengthOfBytesBlockWriter[[]byte](bytesVTB)
+		return block.NewAnyBlockWriter(bw), nil
+
+	case wire.VarintType:
+		if dedupe { // Deduplication for Varint is not standard/implemented.
+			return nil, fmt.Errorf("unimplemented: deduping VARINT")
+		}
+		// Varint values are written without length labels by default (label is nil from NewAnyNoLabelBlockWriter).
+		// The actual Varint encoding happens in this ValueToBytesFunc.
+		varintVTB := func(v interface{}) ([]byte, error) {
+			switch val := v.(type) {
+			case int:
+				return varint.ZigZagEncodeInt64(int64(val)), nil
+			case int64:
+				return varint.ZigZagEncodeInt64(val), nil
+			case *big.Int:
+				return varint.ZigZagEncode(val), nil
+			case float64:
+				// Check if float64 is a whole number
+				if val == math.Trunc(val) {
+					return varint.ZigZagEncodeInt64(int64(val)), nil
+				}
+				return nil, fmt.Errorf("float64 value %v is not a whole number for VarintType block", val)
+			default:
+				return nil, fmt.Errorf("expected int, int64, *big.Int or whole float64 for VarintType block, got %T for value %v", v, v)
+			}
+		}
+		// Varints are not labeled with their length; their encoding is self-terminating.
+		return block.NewAnyNoLabelBlockWriter(varintVTB), nil
+
+	case wire.Float64Type:
+		if dedupe { // Deduplication for Float64 is not standard/implemented.
+			return nil, fmt.Errorf("unimplemented: deduping FLOAT64")
+		}
+		// Float64 values are written without length labels by default.
+		floatVTB := func(v interface{}) ([]byte, error) {
+			var f float64
+			switch val := v.(type) {
+			case float64:
+				f = val
+			case float32:
+				f = float64(val)
+			case int:
+				f = float64(val)
+			case int64:
+				f = float64(val)
+			default:
+				return nil, fmt.Errorf("expected float64 compatible type for Float64Type block, got %T for value %v", v, v)
+			}
+			var b [8]byte // Float64 is 8 bytes.
+			binary.LittleEndian.PutUint64(b[:], math.Float64bits(f))
+			return b[:], nil
+		}
+		// Floats are fixed-width, so no length label is needed.
+		return block.NewAnyNoLabelBlockWriter(floatVTB), nil
+
+	case wire.FixedType:
+		fixedType := t.(wire.FixedType)
+		if dedupe { // Deduplication for FixedType is not standard/implemented.
+			return nil, fmt.Errorf("unimplemented: deduping FIXED")
+		}
+		fixedVTB := func(v interface{}) ([]byte, error) {
+			b, ok := v.([]byte)
+			if !ok {
+				return nil, fmt.Errorf("expected []byte for FixedType block, got %T for value %v", v, v)
+			}
+			if len(b) != fixedType.Length {
+				return nil, fmt.Errorf("fixedType expected %d bytes, got %d for value %v", fixedType.Length, len(b), b)
+			}
+			return b, nil
+		}
+		// Fixed-length types do not need length labels.
+		return block.NewAnyNoLabelBlockWriter(fixedVTB), nil
+
+	default:
+		return nil, fmt.Errorf("unsupported block writer type %s (underlying Go type: %T)", wire.Print(t), t)
+	}
+}
+
+// bytesDeduplicatingAdapter is a specialized AnyBlockWriter adapter for BytesType when deduplication is enabled.
+// It wraps a DeduplicatingBlockWriter[string] and handles the conversion of input []byte values
+// to string keys for the underlying deduplicator.
+type bytesDeduplicatingAdapter struct {
+	coreWriter *block.DeduplicatingBlockWriter[string] // Underlying writer uses string keys for deduplication.
+}
+
+// Write converts the input value `v` (expected to be []byte or string) to a string key
+// and passes it to the underlying string-keyed DeduplicatingBlockWriter.
+func (a *bytesDeduplicatingAdapter) Write(v interface{}) (*label.Label, error) {
+	bytesVal, ok := v.([]byte)
+	if !ok {
+		// Allow string input as well, interpreting it as bytes.
+		if strVal, okStr := v.(string); okStr {
+			bytesVal = []byte(strVal)
+		} else {
+			return nil, fmt.Errorf("bytesDeduplicatingAdapter expected []byte or string, got %T for value %v", v, v)
+		}
+	}
+	// The coreWriter expects a string for deduplication; string(bytesVal) serves as the key.
+	return a.coreWriter.Write(string(bytesVal))
+}
+
+// AllValuesAsBytes delegates to the underlying coreWriter.
+func (a *bytesDeduplicatingAdapter) AllValuesAsBytes() [][]byte {
+	return a.coreWriter.AllValuesAsBytes()
+}
+
+// WriteLastToBuf delegates to the underlying coreWriter.
+func (a *bytesDeduplicatingAdapter) WriteLastToBuf(buf buf.Write) error {
+	return a.coreWriter.WriteLastToBuf(buf)
+}
+
+// getWriter retrieves an existing block.AnyBlockWriter for the given blockDef.Key, or creates
+// a new one if it doesn't exist. Created writers are stored in ae.writers for reuse.
+// `valueWireType` is typically the `Of` type of the `blockDef` (e.g., wire.String for a block of strings).
+func (ae *ArgoEncoder) getWriter(blockDef wire.BlockType, valueWireType wire.Type) (block.AnyBlockWriter, error) {
+	if entry, found := ae.writers.Get(blockDef.Key); found {
+		return entry.Writer, nil
+	}
+	// Create a new writer if one doesn't exist for this block key.
+	writer, err := ae.makeBlockWriter(valueWireType, blockDef.Dedupe)
+	if err != nil {
+		return nil, fmt.Errorf("failed to make block writer for key '%s' (value type %s): %w", blockDef.Key, wire.Print(valueWireType), err)
+	}
+	ae.writers.Set(blockDef.Key, writerEntry{Writer: writer, OriginalValueType: valueWireType})
+	return writer, nil
+}
+
+// Write is a core method for handling scalar values that are part of a block.
+// It retrieves or creates the appropriate block writer for `blockDef`,
+// writes the value `v` to this writer (which generates a label and stores bytes),
+// and then writes the label (if any) to the encoder's coreBuf.
+// If the `HeaderInlineEverythingFlag` is set, it also writes the value's bytes directly
+// to the coreBuf for certain types of labels (e.g., length labels, non-null markers for unlabeled types).
+func (ae *ArgoEncoder) Write(blockDef wire.BlockType, valueWireType wire.Type, v interface{}) (*label.Label, error) {
+	writer, err := ae.getWriter(blockDef, valueWireType)
+	if err != nil {
+		return nil, err // Error from getWriter already has context.
+	}
+
+	lbl, err := writer.Write(v) // Value `v` is written to the chosen block writer.
+	if err != nil {
+		return nil, fmt.Errorf("block writer for key '%s' (value type %s) failed: %w", blockDef.Key, wire.Print(valueWireType), err)
+	}
+
+	// Part 1: Write the label to the core buffer.
+	// This happens regardless of InlineEverything, as labels are part of the core stream.
+	if lbl != nil {
+		encodedLabel := lbl.Encode()
+		if _, err := ae.coreBuf.Write(encodedLabel); err != nil {
+			// Error context for label writing.
+			mode := "non-inline"
+			if ae.header.GetFlag(header.HeaderInlineEverythingFlag) {
+				mode = "inline"
+			}
+			return nil, fmt.Errorf("failed to write label to core buffer (mode: %s): %w", mode, err)
+		}
+	}
+
+	// Part 2: If InlineEverything is active, write the data bytes to coreBuf if appropriate.
+	if ae.header.GetFlag(header.HeaderInlineEverythingFlag) {
+		shouldWriteDataInline := false
+		if lbl == nil {
+			// For unlabeled types (e.g., FLOAT64, FIXED non-nullable), their data is always written inline.
+			shouldWriteDataInline = true
+		} else {
+			// For labeled types, data is written inline only if the label isn't a "standalone" one
+			// (i.e., if it implies data should follow, like a length or NonNull marker).
+			// Backreferences, Null, Absent, Error labels do not have following data in the core stream.
+			isStandaloneLabel := lbl.IsBackref() || lbl.IsNull() || lbl.IsAbsent() || lbl.IsError()
+			if !isStandaloneLabel {
+				shouldWriteDataInline = true
+			}
+		}
+
+		if shouldWriteDataInline {
+			// WriteLastToBuf gets the most recent value from the block writer and writes it to coreBuf.
+			if err := writer.WriteLastToBuf(ae.coreBuf); err != nil {
+				return nil, fmt.Errorf("failed to write value data to core buffer in inline mode: %w", err)
+			}
+		}
+	}
+	// If not InlineEverything, value bytes remain in their respective block writers (writer.valuesAsBytes)
+	// and are assembled into the final message by GetResult().
+
+	return lbl, nil
+}
+
+// ValueToArgoWithType is the primary entry point for encoding a Go data structure (typically from JSON-like input)
+// into the Argo format based on a provided wire.Type schema.
+// The `v` interface{} is expected to conform to the structure defined by `wt`.
+// For example, if `wt` is a RecordType, `v` should be an *orderedmap.OrderedMap[string, interface{}].
+// If `wt` is an ArrayType, `v` should be a slice or array.
+// Debugging information, if enabled, is written to "tmp-gowritelog.json".
+func (ae *ArgoEncoder) ValueToArgoWithType(v interface{}, wt wire.Type) error {
+	// Start recursive encoding. currentPath is initially nil, currentBlock is initially nil.
+	err := ae.writeArgo(nil, v, wt, nil)
+
+	// If debugging is enabled, write the tracked encoding steps to a JSON file.
+	if ae.Debug {
+		jsony := make([]*util.OrderedMapJSON[string, any], len(ae.tracked))
+		for i, obj := range ae.tracked {
+			jsony[i] = util.NewOrderedMapJSON(obj)
+		}
+		trackedJSON, jsonErr := json.MarshalIndent(jsony, "", "  ")
+		if jsonErr != nil {
+			// Log marshalling error, but don't let it hide the main encoding error.
+			fmt.Fprintf(os.Stderr, "Error marshalling debug tracking data: %v\n", jsonErr)
+		} else {
+			_ = os.WriteFile("tmp-gowritelog.json", trackedJSON, 0644) // Error is ignored for debug artifact.
+		}
+	}
+	return err
+}
+
+// writeArgo is the main recursive workhorse for encoding. It traverses the input data `v`
+// according to the structure defined by the wire.Type `wt`.
+// `currentPath` tracks the path within the data structure for debugging.
+// `currentBlock` points to the wire.BlockType definition if the current context is writing
+// elements into a specific block (e.g., a block of strings or varints).
+func (ae *ArgoEncoder) writeArgo(currentPath ast.Path, v interface{}, wt wire.Type, currentBlock *wire.BlockType) error {
+	ae.Track(currentPath, "writeArgo type: "+string(wt.GetTypeKey()), ae.coreBuf, v)
+
+	switch typedWt := wt.(type) {
+	case wire.NullableType:
+		if v == nil { // Handle explicit Go nil for a nullable type.
+			ae.Track(currentPath, "null", ae.coreBuf, label.Null)
+			_, err := ae.coreBuf.Write(label.Null)
+			return err
+		}
+
+		// Handle inline errors: if `v` is an error or []error, write Argo error representation.
+		// This needs to check various ways an error or slice of errors might be represented in `v`.
+		var errorArray []error
+		if errVal, ok := v.(error); ok {
+			errorArray = []error{errVal} // Single error.
+		} else if errSlice, ok := v.([]error); ok {
+			errorArray = errSlice // Already a slice of errors.
+		} else if interfaceSlice, ok := v.([]interface{}); ok {
+			// Check if []interface{} contains only errors.
+			canBeErrorArray := true
+			for _, item := range interfaceSlice {
+				if errVal, itemIsErr := item.(error); itemIsErr {
+					errorArray = append(errorArray, errVal)
+				} else {
+					canBeErrorArray = false // Found a non-error item.
+					break
+				}
+			}
+			if !canBeErrorArray {
+				errorArray = nil // Not a pure error array.
+			}
+		}
+
+		if len(errorArray) > 0 {
+			// Value is an error or slice of errors, write it in Argo error format.
+			ae.Track(currentPath, "error value encountered", ae.coreBuf, v)
+			if _, err := ae.coreBuf.Write(label.Error); err != nil { // Write the Error marker label.
+				return err
+			}
+			// Write the number of errors as a length label.
+			lenLabel := label.NewFromInt64(int64(len(errorArray)))
+			if _, err := ae.coreBuf.Write(lenLabel.Encode()); err != nil {
+				return err
+			}
+			// Write each error.
+			for i, e := range errorArray {
+				errPath := util.AddPathIndex(currentPath, i) // Path for this specific error in the array.
+				if ae.header.GetFlag(header.HeaderSelfDescribingErrorsFlag) {
+					// Use self-describing format for errors.
+					if err := ae.writeSelfDescribing(errPath, e); err != nil {
+						return fmt.Errorf("failed to write self-describing error item at index %d: %w", i, err)
+					}
+				} else {
+					// Use structured Argo error format (defined by wire.Error type).
+					if err := ae.writeGoError(errPath, e); err != nil {
+						return fmt.Errorf("failed to write structured error item at index %d: %w", i, err)
+					}
+				}
+			}
+			return nil // Successfully wrote error(s).
+		}
+
+		// If not nil and not an error, it's a non-null instance of the underlying type.
+		// If the underlying type is not intrinsically labeled (e.g. scalars in blocks often are),
+		// a NonNull marker is needed here before writing the actual value.
+		if !wire.IsLabeled(typedWt.Of) {
+			ae.Track(currentPath, "non-null marker for nullable type", ae.coreBuf, label.NonNull)
+			if _, err := ae.coreBuf.Write(label.NonNull); err != nil {
+				return err
+			}
+		}
+		// Continue writing with the underlying type.
+		return ae.writeArgo(currentPath, v, typedWt.Of, currentBlock)
+
+	case wire.BlockType:
+		if currentBlock != nil {
+			// This should not happen if wire types are structured correctly (no nested blocks).
+			return fmt.Errorf("encoder error: already processing block '%s', cannot switch to new block '%s' at path %s. Wire type: %s",
+				currentBlock.Key, typedWt.Key, util.FormatPath(currentPath), wire.Print(wt))
+		}
+		ae.Track(currentPath, "entering block with key", ae.coreBuf, typedWt.Key)
+		// Recursively call writeArgo with the block's element type (`typedWt.Of`)
+		// and pass `&typedWt` as the new `currentBlock` context.
+		return ae.writeArgo(currentPath, v, typedWt.Of, &typedWt)
+
+	case wire.RecordType:
+		ae.Track(currentPath, "record with number of fields", ae.coreBuf, len(typedWt.Fields))
+		// Expect v to be an *orderedmap.OrderedMap for records to maintain field order.
+		om, ok := v.(*orderedmap.OrderedMap[string, interface{}])
+		if !ok && v != nil { // If v is not nil, it must be the correct map type.
+			return fmt.Errorf("type error: expected *orderedmap.OrderedMap[string, interface{}] for record, got %T at path %s", v, util.FormatPath(currentPath))
+		}
+
+		// Iterate through fields as defined in the wire.RecordType to ensure correct order and handling of all defined fields.
+		for _, field := range typedWt.Fields {
+			fieldPath := util.AddPathName(currentPath, field.Name)
+			var fieldValue interface{}
+			var fieldExists bool
+			if om != nil { // If input map is nil (because parent was nil), all fields are treated as absent.
+				fieldValue, fieldExists = om.Get(field.Name)
+			} else {
+				fieldValue = nil // Effectively absent.
+				fieldExists = false
+			}
+
+			if fieldExists && fieldValue != nil && fieldValue != wire.AbsentValue {
+				// Field is present and has a non-nil, non-absent value.
+				// If omittable and its underlying type isn't self-labeling (like a BlockType often is),
+				// write a NonNull marker to indicate its presence.
+				if field.Omittable && !wire.IsLabeled(field.Of) {
+					ae.Track(fieldPath, "omittable record field present, writing NonNull marker", ae.coreBuf, field.Name)
+					if _, err := ae.coreBuf.Write(label.NonNull); err != nil {
+						return err
+					}
+				}
+				// Recursively write the field's value.
+				if err := ae.writeArgo(fieldPath, fieldValue, field.Of, currentBlock); err != nil {
+					return err
+				}
+			} else if field.Omittable && (!fieldExists || fieldValue == wire.AbsentValue) {
+				// Field is omittable and is effectively absent (either not in map or explicit AbsentValue).
+				ae.Track(fieldPath, "omittable record field absent, writing Absent marker", ae.coreBuf, field.Name)
+				if _, err := ae.coreBuf.Write(label.Absent); err != nil {
+					return err
+				}
+			} else if wire.IsNullable(field.Of) {
+				// Field is not omittable (or omittable but present as nil) AND its type is nullable.
+				// This handles cases where an explicit JSON null was provided for a nullable field,
+				// or a non-omittable field is nil (which is only valid if its type is nullable).
+				ae.Track(fieldPath, "record field is nil and type is nullable (or non-omittable field is nil), recursing", ae.coreBuf, field.Name)
+				// Recursively call writeArgo. If fieldValue is nil, this will correctly write a Null label via the NullableType case.
+				if err := ae.writeArgo(fieldPath, fieldValue, field.Of, currentBlock); err != nil {
+					return err
+				}
+			} else if wire.IsBlock(field.Of) && wire.IsDesc(field.Of.(wire.BlockType).Of) {
+				// Special case: field is a Block of SelfDescribing (DESC) type and is absent/nil.
+				// SelfDescribing types can represent null, so we recurse to let DESC handle the nil.
+				ae.Track(fieldPath, "record field is nil/absent but is Block<DESC>, recursing for self-describing null", ae.coreBuf, field.Name)
+				if err := ae.writeArgo(fieldPath, nil, field.Of, currentBlock); err != nil {
+					return err
+				}
+			} else {
+				// Field is absent/nil, but it's not omittable, not nullable, and not Block<DESC>.
+				// This is a data-schema mismatch.
+				return fmt.Errorf("schema error: record field '%s' is absent/nil but its type (%s) is not omittable, not nullable, and not Block<DESC> at path %s", field.Name, wire.Print(field.Of), util.FormatPath(fieldPath))
+			}
+		}
+		return nil
+
+	case wire.ArrayType:
+		reflectVal := reflect.ValueOf(v)
+		if reflectVal.Kind() != reflect.Slice && reflectVal.Kind() != reflect.Array {
+			// If `v` is nil for an ArrayType, it's an error because ArrayType itself is not nullable.
+			// A nullable array would be NullableType{Of: ArrayType{...}}.
+			if v == nil {
+				return fmt.Errorf("type error: cannot encode Go nil as non-nullable Argo array at path %s. WireType: %s", util.FormatPath(currentPath), wire.Print(wt))
+			}
+			return fmt.Errorf("type error: expected slice or array for ArrayType, got %T at path %s", v, util.FormatPath(currentPath))
+		}
+		length := reflectVal.Len()
+		ae.Track(currentPath, "array with length", ae.coreBuf, length)
+		lenLabel := label.NewFromInt64(int64(length)) // Label for array length.
+		if _, err := ae.coreBuf.Write(lenLabel.Encode()); err != nil {
+			return err
+		}
+		// Recursively write each element of the array.
+		for i := 0; i < length; i++ {
+			itemPath := util.AddPathIndex(currentPath, i)
+			itemValue := reflectVal.Index(i).Interface()
+			if err := ae.writeArgo(itemPath, itemValue, typedWt.Of, currentBlock); err != nil {
+				return err
+			}
+		}
+		return nil
+
+	case wire.BooleanType:
+		bVal, ok := v.(bool)
+		if !ok {
+			return fmt.Errorf("expected bool for BooleanType, got %T at path %s", v, util.FormatPath(currentPath))
+		}
+		ae.Track(currentPath, "boolean", ae.coreBuf, bVal)
+		if bVal {
+			_, err := ae.coreBuf.Write(label.True)
+			return err
+		}
+		_, err := ae.coreBuf.Write(label.False)
+		return err
+
+	case wire.StringType, wire.BytesType, wire.VarintType, wire.Float64Type, wire.FixedType:
+		// Logic for types which may use blocks for data
+		if currentBlock == nil {
+			return fmt.Errorf("programmer error: need block for %s at path %s", wire.Print(wt), util.FormatPath(currentPath))
+		}
+		_, err := ae.Write(*currentBlock, wt, v)
+		if err != nil {
+			return err
+		}
+		ae.Track(currentPath, string(wt.GetTypeKey()), ae.coreBuf, v)
+		return nil
+
+	case wire.DescType:
+		ae.Track(currentPath, "self-describing", ae.coreBuf, v)
+		return ae.writeSelfDescribing(currentPath, v)
+
+	case wire.PathType: // Argo spec: PATH values ... encoded exactly as an ARRAY of VARINT values.
+		// This should be handled by the Error type definition, which includes a PATH field.
+		// If we encounter a raw PathType, treat it as Array{Of: Varint}.
+		pathSlice, ok := v.([]interface{})
+		if !ok {
+			if intSlice, isIntSlice := v.([]int); isIntSlice {
+				pathSlice = make([]interface{}, len(intSlice))
+				for i, v := range intSlice {
+					pathSlice[i] = v
+				}
+				ok = true
+			} else if int64Slice, isInt64Slice := v.([]int64); isInt64Slice {
+				pathSlice = make([]interface{}, len(int64Slice))
+				for i, v := range int64Slice {
+					pathSlice[i] = v
+				}
+				ok = true
+			} else {
+				return fmt.Errorf("expected []interface{} or []int or []int64 for PathType, got %T at path %s", v, util.FormatPath(currentPath))
+			}
+		}
+		// The actual transformation from GraphQL path to wire path (list of integers) happens
+		// before this point if we are encoding a structured Error.
+		// Here, we assume 'v' is already the list of integers for the wire.
+		return ae.writeArgo(currentPath, pathSlice, wire.ArrayType{Of: wire.Varint}, currentBlock)
+
+	default:
+		return fmt.Errorf("unsupported wire type %T (%s) for encoding at path %s", wt, wire.Print(wt), util.FormatPath(currentPath))
+	}
+}
+
+// writeSelfDescribing writes a Go value in Argo's self-describing format.
+// This format uses specific leading bytes to indicate the type of the following data.
+// It's used for errors when HeaderSelfDescribingErrorsFlag is set, or for fields of type wire.Desc.
+func (ae *ArgoEncoder) writeSelfDescribing(currentPath ast.Path, v interface{}) error {
+	ae.Track(currentPath, "writeSelfDescribing value", ae.coreBuf, v)
+	if v == nil {
+		_, err := ae.coreBuf.Write(wire.SelfDescribingNull) // Write the null marker.
+		return err
+	}
+
+	// Optimized path for *orderedmap.OrderedMap (common for objects).
+	if om, ok := v.(*orderedmap.OrderedMap[string, interface{}]); ok {
+		if _, err := ae.coreBuf.Write(wire.SelfDescribingObject); err != nil { // Object marker.
+			return err
+		}
+		numFields := om.Len()
+		lenLabel := label.NewFromInt64(int64(numFields)) // Length of object (number of fields).
+		if _, err := ae.coreBuf.Write(lenLabel.Encode()); err != nil {
+			return err
+		}
+
+		// Iterate through fields of the ordered map.
+		for el := om.Front(); el != nil; el = el.Next() {
+			k := el.Key   // Field name
+			v := el.Value // Field value
+			fieldPath := util.AddPathName(currentPath, k)
+
+			// Write field name (as a self-describing string).
+			stringBlockKey := wire.BlockKey("String") // Standard key for self-describing strings.
+			stringElementType, blockDefOk := wire.SelfDescribingBlocks[stringBlockKey]
+			if !blockDefOk {
+				return fmt.Errorf("internal error: self-describing string block key ('%s') not found in wire.SelfDescribingBlocks map for field name '%s'", stringBlockKey, k)
+			}
+			selfDescribingStringBlock := wire.NewBlockType(stringElementType, stringBlockKey, wire.MustDeduplicateByDefault(stringElementType))
+			if _, err := ae.Write(selfDescribingStringBlock, wire.String, k); err != nil {
+				return fmt.Errorf("failed to write self-describing object field name '%s': %w", k, err)
+			}
+
+			// Recursively write field value in self-describing format.
+			if err := ae.writeSelfDescribing(fieldPath, v); err != nil {
+				return fmt.Errorf("failed to write self-describing object field value for '%s': %w", k, err)
+			}
+		}
+		return nil
+	}
+
+	// General path using reflection for other types.
+	val := reflect.ValueOf(v)
+	switch val.Kind() {
+	case reflect.Map:
+		// Handles native Go maps (e.g., map[string]interface{}).
+		// For determinism, these are converted to *orderedmap.OrderedMap before recursive call.
+		if val.Type().Key().Kind() != reflect.String {
+			return fmt.Errorf("type error: cannot encode map with non-string keys in self-describing object at path %s (type: %T)", util.FormatPath(currentPath), v)
+		}
+
+		ae.Track(currentPath, "converting native map to OrderedMap for self-describing encoding", ae.coreBuf, v)
+		tempOM := orderedmap.NewOrderedMap[string, interface{}]()
+		var stringKeys []string
+		for _, kVal := range val.MapKeys() {
+			stringKeys = append(stringKeys, kVal.String())
+		}
+		sort.Strings(stringKeys) // Sort keys for deterministic order in the temporary OrderedMap.
+
+		for _, sk := range stringKeys {
+			mapValue := val.MapIndex(reflect.ValueOf(sk)).Interface()
+			tempOM.Set(sk, mapValue)
+		}
+		return ae.writeSelfDescribing(currentPath, tempOM) // Recurse with the ordered map.
+
+	case reflect.Slice, reflect.Array:
+		// Handle []byte separately as SelfDescribingBytes.
+		if byteSlice, isBytes := v.([]byte); isBytes {
+			if _, err := ae.coreBuf.Write(wire.SelfDescribingBytes); err != nil { // Bytes marker.
+				return err
+			}
+			bytesBlockKey := wire.BlockKey("Bytes") // Standard key for self-describing byte arrays.
+			bytesElementType, blockDefOk := wire.SelfDescribingBlocks[bytesBlockKey]
+			if !blockDefOk {
+				return fmt.Errorf("internal error: self-describing bytes block key ('%s') not found in wire.SelfDescribingBlocks map", bytesBlockKey)
+			}
+			selfDescribingBytesBlock := wire.NewBlockType(bytesElementType, bytesBlockKey, wire.MustDeduplicateByDefault(bytesElementType))
+			_, err := ae.Write(selfDescribingBytesBlock, wire.Bytes, byteSlice)
+			return err
+		}
+
+		// Other slices/arrays are SelfDescribingList.
+		if _, err := ae.coreBuf.Write(wire.SelfDescribingList); err != nil { // List marker.
+			return err
+		}
+		length := val.Len()
+		lenLabel := label.NewFromInt64(int64(length)) // Length of list.
+		if _, err := ae.coreBuf.Write(lenLabel.Encode()); err != nil {
+			return err
+		}
+		// Recursively write each list item in self-describing format.
+		for i := 0; i < length; i++ {
+			itemPath := util.AddPathIndex(currentPath, i)
+			if err := ae.writeSelfDescribing(itemPath, val.Index(i).Interface()); err != nil {
+				return fmt.Errorf("error writing self-describing list item at index %d (path %s): %w", i, util.FormatPath(itemPath), err)
+			}
+		}
+		return nil
+
+	case reflect.String:
+		if _, err := ae.coreBuf.Write(wire.SelfDescribingString); err != nil { // String marker.
+			return err
+		}
+		stringBlockKey := wire.BlockKey("String")
+		stringElementType, blockDefOk := wire.SelfDescribingBlocks[stringBlockKey]
+		if !blockDefOk {
+			return fmt.Errorf("internal error: self-describing string block key ('%s') not found in wire.SelfDescribingBlocks map", stringBlockKey)
+		}
+		selfDescribingStringBlock := wire.NewBlockType(stringElementType, stringBlockKey, wire.MustDeduplicateByDefault(stringElementType))
+		_, err := ae.Write(selfDescribingStringBlock, wire.String, v.(string))
+		return err
+
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		if _, err := ae.coreBuf.Write(wire.SelfDescribingInt); err != nil { // Integer marker.
+			return err
+		}
+		varintBlockKey := wire.BlockKey("Int") // Standard key for self-describing integers.
+		varintElementType, blockDefOk := wire.SelfDescribingBlocks[varintBlockKey]
+		if !blockDefOk {
+			return fmt.Errorf("internal error: self-describing varint block key ('%s') not found in wire.SelfDescribingBlocks map", varintBlockKey)
+		}
+		selfDescribingVarintBlock := wire.NewBlockType(varintElementType, varintBlockKey, wire.MustDeduplicateByDefault(varintElementType))
+		_, err := ae.Write(selfDescribingVarintBlock, wire.Varint, val.Int()) // val.Int() converts various int types to int64 for varint encoder.
+		return err
+
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		uVal := val.Uint()
+		if _, err := ae.coreBuf.Write(wire.SelfDescribingInt); err != nil {
+			return err
+		}
+		varintBlockKey := wire.BlockKey("Int")
+		varintElementType, blockDefOk := wire.SelfDescribingBlocks[varintBlockKey]
+		if !blockDefOk {
+			return fmt.Errorf("internal error: self-describing varint block key ('%s') not found for uint value", varintBlockKey)
+		}
+		selfDescribingVarintBlock := wire.NewBlockType(varintElementType, varintBlockKey, wire.MustDeduplicateByDefault(varintElementType))
+		if uVal <= math.MaxInt64 { // If fits in int64, use that directly for varint encoder.
+			_, err := ae.Write(selfDescribingVarintBlock, wire.Varint, int64(uVal))
+			return err
+		}
+		// Otherwise, use *big.Int for varint encoding.
+		bigUVal := new(big.Int).SetUint64(uVal)
+		_, err := ae.Write(selfDescribingVarintBlock, wire.Varint, bigUVal)
+		return err
+
+	case reflect.Float32, reflect.Float64:
+		fVal := val.Float()
+		if fVal == math.Trunc(fVal) && fVal >= float64(math.MinInt64) && fVal <= float64(math.MaxInt64) {
+			// If float is a whole number and fits in int64, encode as SelfDescribingInt.
+			if _, err := ae.coreBuf.Write(wire.SelfDescribingInt); err != nil {
+				return err
+			}
+			varintBlockKey := wire.BlockKey("Int")
+			varintElementType, blockDefOk := wire.SelfDescribingBlocks[varintBlockKey]
+			if !blockDefOk {
+				return fmt.Errorf("internal error: self-describing varint block key ('%s') not found for whole float", varintBlockKey)
+			}
+			selfDescribingVarintBlock := wire.NewBlockType(varintElementType, varintBlockKey, wire.MustDeduplicateByDefault(varintElementType))
+			_, err := ae.Write(selfDescribingVarintBlock, wire.Varint, int64(fVal))
+			return err
+		}
+		// Otherwise, encode as SelfDescribingFloat.
+		if _, err := ae.coreBuf.Write(wire.SelfDescribingFloat); err != nil { // Float marker.
+			return err
+		}
+		floatBlockKey := wire.BlockKey("Float") // Standard key for self-describing floats.
+		floatElementType, blockDefOk := wire.SelfDescribingBlocks[floatBlockKey]
+		if !blockDefOk {
+			return fmt.Errorf("internal error: self-describing float block key ('%s') not found in wire.SelfDescribingBlocks map", floatBlockKey)
+		}
+		selfDescribingFloatBlock := wire.NewBlockType(floatElementType, floatBlockKey, wire.MustDeduplicateByDefault(floatElementType))
+		_, err := ae.Write(selfDescribingFloatBlock, wire.Float64, fVal)
+		return err
+
+	case reflect.Bool:
+		if v.(bool) {
+			_, err := ae.coreBuf.Write(wire.SelfDescribingTrue) // True marker.
+			return err
+		}
+		_, err := ae.coreBuf.Write(wire.SelfDescribingFalse) // False marker.
+		return err
+
+	case reflect.Ptr, reflect.Interface:
+		if val.IsNil() { // Handle nil pointer or nil interface.
+			_, err := ae.coreBuf.Write(wire.SelfDescribingNull)
+			return err
+		}
+		// Dereference pointer/interface and recurse with the element.
+		return ae.writeSelfDescribing(currentPath, val.Elem().Interface())
+
+	default:
+		// Handle *big.Int specifically, as it's a common type for large integers not caught by reflect.Int types.
+		if bigIntValue, isBigInt := v.(*big.Int); isBigInt {
+			if _, err := ae.coreBuf.Write(wire.SelfDescribingInt); err != nil {
+				return err
+			}
+			varintBlockKey := wire.BlockKey("Int")
+			varintElementType, blockDefOk := wire.SelfDescribingBlocks[varintBlockKey]
+			if !blockDefOk {
+				return fmt.Errorf("internal error: self-describing varint block key ('%s') not found for *big.Int", varintBlockKey)
+			}
+			selfDescribingVarintBlock := wire.NewBlockType(varintElementType, varintBlockKey, wire.MustDeduplicateByDefault(varintElementType))
+			_, err := ae.Write(selfDescribingVarintBlock, wire.Varint, bigIntValue)
+			return err
+		}
+		return fmt.Errorf("type error: cannot encode unsupported Go type %T (Kind: %s) in self-describing format at path %s", v, val.Kind(), util.FormatPath(currentPath))
+	}
+}
+
+// ArgoErrorValue defines the structure for representing GraphQL errors in Argo format when not using self-describing errors.
+// It includes standard GraphQL error fields. The `Path` is transformed into a list of integers/strings for Argo.
+type ArgoErrorValue struct {
+	Message    string                                      // The error message.
+	Locations  []ArgoErrorLocation                         // Source locations of the error in the query.
+	Path       []interface{}                               // Path to the field where the error occurred, as a list of string field names and integer indices.
+	Extensions *orderedmap.OrderedMap[string, interface{}] // Custom error data.
+}
+
+// ArgoErrorLocation represents a single source location (line and column) for an error.
+type ArgoErrorLocation struct {
+	Line   int `json:"line"`   // 1-indexed line number.
+	Column int `json:"column"` // 1-indexed column number.
+}
+
+// writeGoError converts a standard Go `error` into an ArgoErrorValue (represented as an *orderedmap.OrderedMap for deterministic field order)
+// and then writes this map using the structured `wire.Error` type definition.
+// This is invoked when the `HeaderSelfDescribingErrorsFlag` is false.
+// `currentPath` is the GraphQL path to where the error label itself is being written.
+func (ae *ArgoEncoder) writeGoError(currentPath ast.Path, goErr error) error {
+	// Construct the ArgoErrorValue.
+	argoErrVal := ArgoErrorValue{
+		Message: goErr.Error(),
+		// Locations and Path are typically not available from a generic Go error directly.
+		// These would need to be populated if `goErr` is a more structured error type
+		// that carries GraphQL-specific location/path information.
+		// For now, we add the Go error type to extensions for some context.
+		Extensions: orderedmap.NewOrderedMap[string, interface{}](),
+	}
+	argoErrVal.Extensions.Set("go_error_type", reflect.TypeOf(goErr).String())
+
+	// Convert ArgoErrorValue to an *orderedmap.OrderedMap for encoding with wire.Error type.
+	// The order of Set calls determines the field order in the Argo output if wire.Error is a RecordType.
+	errorMap := orderedmap.NewOrderedMap[string, interface{}]()
+	errorMap.Set("message", argoErrVal.Message)
+	if argoErrVal.Locations != nil { // Only include if present.
+		errorMap.Set("locations", argoErrVal.Locations)
+	}
+	if argoErrVal.Path != nil { // Only include if present.
+		errorMap.Set("path", argoErrVal.Path)
+	}
+	if argoErrVal.Extensions != nil && argoErrVal.Extensions.Len() > 0 { // Only include if non-empty.
+		errorMap.Set("extensions", argoErrVal.Extensions)
+	}
+
+	// Write the errorMap using the predefined wire.Error schema.
+	// currentBlock is nil as errors are part of the core stream, not typically within other blocks.
+	return ae.writeArgo(currentPath, errorMap, wire.Error, nil)
+}
+
+// GetResult finalizes the encoding process. It assembles the Argo header,
+// data from all block writers (if not inlining everything), and the core buffer data
+// into a single, final *buf.Buf containing the complete Argo message.
+func (ae *ArgoEncoder) GetResult() (*buf.Buf, error) {
+	headerBytes, err := ae.header.AsBytes() // Serialize the header to bytes.
+	if err != nil {
+		return nil, fmt.Errorf("failed to serialize Argo header: %w", err)
+	}
+	ae.Track(nil, "header bytes written", nil, headerBytes) // For debugging, length of header.
+
+	shouldWriteBlocks := !ae.header.GetFlag(header.HeaderInlineEverythingFlag)
+	totalDataBytesFromBlocks := 0   // Total size of content from all blocks.
+	blockLengthLabelBytesTotal := 0 // Total size of all block length labels.
+
+	// blockToWrite temporarily stores data for each block before final assembly.
+	type blockToWrite struct {
+		key             wire.BlockKey // The block's unique key.
+		lengthLabelData []byte        // Encoded label for the total length of this block's content.
+		contentBytes    [][]byte      // Slice of byte slices, each representing a value in the block.
+	}
+	var blocksToWrite []blockToWrite // List of blocks to be written, in order.
+
+	if shouldWriteBlocks {
+		// Iterate through writers in the order they were created (preserved by OrderedMap).
+		// This ensures blocks are written in a deterministic order, matching reference implementations.
+		for el := ae.writers.Front(); el != nil; el = el.Next() {
+			key := el.Key
+			entry := el.Value // writerEntry
+			writer := entry.Writer
+			originalValueType := entry.OriginalValueType // e.g. wire.String, wire.Bytes
+
+			blockContentBytes := writer.AllValuesAsBytes() // Get all accumulated byte values for this block.
+			currentBlockTotalBytes := 0
+
+			isStringBlock := wire.IsString(originalValueType)
+
+			processedBlockContentBytes := make([][]byte, 0, len(blockContentBytes))
+			for _, valueBytes := range blockContentBytes {
+				currentBlockTotalBytes += len(valueBytes)
+				processedBlockContentBytes = append(processedBlockContentBytes, valueBytes)
+				// If it's a string block and null termination is enabled, add terminator.
+				if isStringBlock && ae.header.GetFlag(header.HeaderNullTerminatedStringsFlag) {
+					processedBlockContentBytes = append(processedBlockContentBytes, nullTerminator)
+					currentBlockTotalBytes += len(nullTerminator)
+				}
+			}
+
+			lengthLabel := label.NewFromInt64(int64(currentBlockTotalBytes)) // Label for total length of this block.
+			encodedLengthLabel := lengthLabel.Encode()
+
+			blocksToWrite = append(blocksToWrite, blockToWrite{
+				key:             key,
+				lengthLabelData: encodedLengthLabel,
+				contentBytes:    processedBlockContentBytes,
+			})
+
+			totalDataBytesFromBlocks += currentBlockTotalBytes
+			blockLengthLabelBytesTotal += len(encodedLengthLabel)
+		}
+	}
+
+	coreDataBytes := ae.coreBuf.Bytes() // Get all bytes from the core buffer (labels, inlined data).
+	coreDataLength := len(coreDataBytes)
+	var coreLengthLabelBytes []byte
+	if shouldWriteBlocks { // If blocks are written, the core data also needs a length label.
+		coreLengthLabel := label.NewFromInt64(int64(coreDataLength))
+		coreLengthLabelBytes = coreLengthLabel.Encode()
+	}
+
+	// Calculate the total size of the final Argo message.
+	finalSize := len(headerBytes)
+	if shouldWriteBlocks {
+		finalSize += blockLengthLabelBytesTotal // All block length labels.
+		finalSize += totalDataBytesFromBlocks   // All block content.
+		finalSize += len(coreLengthLabelBytes)  // Core data length label.
+	}
+	finalSize += coreDataLength // Core data itself.
+
+	// Allocate the final buffer and write all parts in order.
+	finalBuf := buf.NewBuf(finalSize)
+
+	_, _ = finalBuf.Write(headerBytes) // 1. Header
+
+	if shouldWriteBlocks {
+		// 2. For each block: its length label, then its content.
+		for _, btw := range blocksToWrite {
+			_, _ = finalBuf.Write(btw.lengthLabelData)
+			for _, valueData := range btw.contentBytes {
+				_, _ = finalBuf.Write(valueData)
+			}
+		}
+		// 3. Core data length label.
+		_, _ = finalBuf.Write(coreLengthLabelBytes)
+	}
+
+	// 4. Core data.
+	_, _ = finalBuf.Write(coreDataBytes)
+
+	// Sanity check the final length.
+	if finalBuf.Len() != finalSize {
+		return nil, fmt.Errorf("internal encoder error: incorrect result length. Wrote %d, expected %d", finalBuf.Len(), finalSize)
+	}
+
+	return finalBuf, nil
+}