feat: implicit array encoding (ADR 002)

ADR 002 - Length-Agnostic Implicit Array Encoding:
- Arrays detected when payload > 8 bytes
- First byte indicates element size (1,2,4,8)
- Element count calculated as (payloadSize - 1) / elementSize
- Support int8/int16/int32/int64 and float32/float64 arrays
- Add PutAccess.AddIntegerArray/AddFloatArray
- Add PackInt64Array/PackFloat64Array high-level functions

Closes ADR-001

Author: heartical

access/generic_decode.go

@@ -9,37 +9,44 @@ import (
 )
 
 // DecodePrimitive interprets a primitive payload directly using type tag and width.
-// It returns a Go value (int, float, string, []byte as string, bool, nil).
-func DecodePrimitive(typ typetags.Type, buf []byte) (interface{}, error) {
+// It returns a Go value (int, float, string, []byte, bool, nil, or array).
+// For integer and floating-point types, if payload size > 8 bytes, it decodes as an array.
+func DecodePrimitive(typ typetags.Type, buf []byte) (any, error) {
 	size := len(buf)
 
 	switch typ {
 	case typetags.TypeInteger:
-		switch size {
-		case 0:
+		switch {
+		case size == 0:
 			return nil, nil
-		case 1:
+		case size == 1:
 			return int8(buf[0]), nil
-		case 2:
+		case size == 2:
 			return int16(binary.LittleEndian.Uint16(buf)), nil
-		case 4:
+		case size == 4:
 			return int32(binary.LittleEndian.Uint32(buf)), nil
-		case 8:
+		case size == 8:
 			return int64(binary.LittleEndian.Uint64(buf)), nil
+		case size > typetags.MaxScalarSize:
+			// Array mode: payload > 8 bytes
+			return decodeIntegerArrayPayload(buf)
 		default:
 			return nil, fmt.Errorf("DecodePrimitive: unsupported integer size %d", size)
 		}
 
 	case typetags.TypeFloating:
-		switch size {
-		case 0:
+		switch {
+		case size == 0:
 			return nil, nil
-		case 4:
+		case size == 4:
 			bits := binary.LittleEndian.Uint32(buf)
 			return math.Float32frombits(bits), nil
-		case 8:
+		case size == 8:
 			bits := binary.LittleEndian.Uint64(buf)
 			return math.Float64frombits(bits), nil
+		case size > typetags.MaxScalarSize:
+			// Array mode: payload > 8 bytes
+			return decodeFloatArrayPayload(buf)
 		default:
 			return nil, fmt.Errorf("DecodePrimitive: unsupported float size %d", size)
 		}
@@ -61,6 +68,32 @@ func DecodePrimitive(typ typetags.Type, buf []byte) (interface{}, error) {
 	}
 }
 
+// decodeIntegerArrayPayload decodes an integer array from the payload
+func decodeIntegerArrayPayload(payload []byte) (any, error) {
+	elementSize, ok := typetags.ArrayElementSize(payload)
+	if !ok {
+		return nil, fmt.Errorf("invalid array element size: %d", payload[0])
+	}
+
+	count := typetags.ArrayElementCount(len(payload), elementSize)
+	data := payload[1:] // Skip the element size indicator
+
+	return decodeIntegerArray(data, elementSize, count)
+}
+
+// decodeFloatArrayPayload decodes a floating-point array from the payload
+func decodeFloatArrayPayload(payload []byte) (any, error) {
+	elementSize, ok := typetags.ArrayElementSize(payload)
+	if !ok {
+		return nil, fmt.Errorf("invalid array element size: %d", payload[0])
+	}
+
+	count := typetags.ArrayElementCount(len(payload), elementSize)
+	data := payload[1:] // Skip the element size indicator
+
+	return decodeFloatArray(data, elementSize, count)
+}
+
 // DecodeTupleGeneric: decode a []any from the current position in a SeqGetAccess.
 // If root is true, the caller already consumed the tuple header.
 // If ordered is true, maps inside the tuple are decoded as *typetags.OrderedMapAny.
@@ -328,3 +361,50 @@ func DecodeOrdered(buf []byte) (any, error) {
 	}
 	return vals, nil
 }
+
+// decodeIntegerArray decodes an integer array
+func decodeIntegerArray(data []byte, elementSize, count int) (any, error) {
+	result := make([]int64, count)
+
+	for i := range count {
+		offset := i * elementSize
+		switch elementSize {
+		case 1:
+			result[i] = int64(data[offset])
+		case 2:
+			result[i] = int64(binary.LittleEndian.Uint16(data[offset:]))
+		case 4:
+			result[i] = int64(binary.LittleEndian.Uint32(data[offset:]))
+		case 8:
+			result[i] = int64(binary.LittleEndian.Uint64(data[offset:]))
+		default:
+			return nil, fmt.Errorf("unsupported element size: %d", elementSize)
+		}
+	}
+
+	return result, nil
+}
+
+// decodeFloatArray decodes a floating-point array
+func decodeFloatArray(data []byte, elementSize, count int) (any, error) {
+	if elementSize != 4 && elementSize != 8 {
+		return nil, fmt.Errorf("unsupported float element size: %d", elementSize)
+	}
+
+	if elementSize == 4 {
+		result := make([]float32, count)
+		for i := 0; i < count; i++ {
+			bits := binary.LittleEndian.Uint32(data[i*4:])
+			result[i] = math.Float32frombits(bits)
+		}
+		return result, nil
+	}
+
+	// elementSize == 8
+	result := make([]float64, count)
+	for i := range count {
+		bits := binary.LittleEndian.Uint64(data[i*8:])
+		result[i] = math.Float64frombits(bits)
+	}
+	return result, nil
+}

access/put.go

@@ -734,3 +734,90 @@ func (p *PutAccess) AddNumericString(val string) error {
 	}
 	return fmt.Errorf("AddNumericString: unsupported numeric string %q", val)
 }
+
+// AddIntegerArray adds an integer array
+func (p *PutAccess) AddIntegerArray(values []int64) {
+	if len(values) == 0 {
+		p.AddNull(nil)
+		return
+	}
+
+	// Determine the minimal element size that can store all values
+	elementSize := determineIntegerSize(values)
+
+	// Create buffer: [elementSize] + [values...]
+	buf := make([]byte, 1+len(values)*elementSize)
+	buf[0] = byte(elementSize)
+
+	// Encode values
+	encodeIntegers(buf[1:], values, elementSize)
+
+	p.offsets = binary.LittleEndian.AppendUint16(p.offsets,
+		typetags.EncodeHeader(p.position, typetags.TypeInteger))
+	p.buf = append(p.buf, buf...)
+	p.position = len(p.buf)
+}
+
+// AddFloatArray adds a floating-point array
+func (p *PutAccess) AddFloatArray(values []float64) {
+	if len(values) == 0 {
+		p.AddNull(nil)
+		return
+	}
+
+	// Always use float64 (8 bytes)
+	elementSize := 8
+	buf := make([]byte, 1+len(values)*elementSize)
+	buf[0] = byte(elementSize)
+
+	for i, v := range values {
+		bits := math.Float64bits(v)
+		binary.LittleEndian.PutUint64(buf[1+i*elementSize:], bits)
+	}
+
+	p.offsets = binary.LittleEndian.AppendUint16(p.offsets,
+		typetags.EncodeHeader(p.position, typetags.TypeFloating))
+	p.buf = append(p.buf, buf...)
+	p.position = len(p.buf)
+}
+
+// determineIntegerSize determines the minimal element size that can store all integers
+func determineIntegerSize(values []int64) int {
+	maxVal := int64(0)
+	minVal := int64(0)
+	for _, v := range values {
+		if v > maxVal {
+			maxVal = v
+		}
+		if v < minVal {
+			minVal = v
+		}
+	}
+
+	switch {
+	case minVal >= math.MinInt8 && maxVal <= math.MaxInt8:
+		return 1
+	case minVal >= math.MinInt16 && maxVal <= math.MaxInt16:
+		return 2
+	case minVal >= math.MinInt32 && maxVal <= math.MaxInt32:
+		return 4
+	default:
+		return 8
+	}
+}
+
+// encodeIntegers encodes integers into the buffer with the given element size
+func encodeIntegers(buf []byte, values []int64, elementSize int) {
+	for i, v := range values {
+		switch elementSize {
+		case 1:
+			buf[i] = byte(v)
+		case 2:
+			binary.LittleEndian.PutUint16(buf[i*2:], uint16(v))
+		case 4:
+			binary.LittleEndian.PutUint32(buf[i*4:], uint32(v))
+		case 8:
+			binary.LittleEndian.PutUint64(buf[i*8:], uint64(v))
+		}
+	}
+}

typetags/types.go

@@ -3,6 +3,9 @@ package typetags
 // Type is a 3-bit tag encoded into a uint16 header
 type Type uint16
 
+// MaxScalarSize is the maximum size of a scalar value (8 bytes)
+const MaxScalarSize = 8
+
 const (
 	TypeInvalid              Type = 0
 	TypeEnd                  Type = 0
@@ -19,7 +22,44 @@ const (
 	TypeMap                  Type = 7
 )
 
-// String returns the human-readable name of the type
+// Extended container constants
+const (
+	ExtendedContainerValueSize = 4 // 4 bytes continuation
+	EndOfChain                 = 0xFFFFFFFF
+)
+
+// ExtendedContainerValue represents the 4-byte management block for extended containers
+type ExtendedContainerValue struct {
+	Continuation uint32 // Absolute 32-bit offset to next segment (or EndOfChain)
+	// SelfOffset   uint32 // Absolute 32-bit address for validation
+}
+
+// IsArray determines whether the payload is an array
+func IsArray(payloadSize int) bool {
+	return payloadSize > MaxScalarSize
+}
+
+// ArrayElementSize returns the element size from the first byte of the payload
+func ArrayElementSize(payload []byte) (int, bool) {
+	if len(payload) == 0 {
+		return 0, false
+	}
+	switch payload[0] {
+	case 1, 2, 4, 8:
+		return int(payload[0]), true
+	default:
+		return 0, false
+	}
+}
+
+// ArrayElementCount calculates the number of elements in the array
+func ArrayElementCount(payloadSize, elementSize int) int {
+	if elementSize <= 0 {
+		return 0
+	}
+	return (payloadSize - 1) / elementSize
+}
+
 func (t Type) String() string {
 	switch t {
 	case TypeInteger: