fix(sdk): emit spec-compliant key access in experimental/tdf and delegate Writer

sdk/experimental/tdf/doc.go

@@ -28,7 +28,6 @@
 //	if err != nil {
 //		log.Fatal(err)
 //	}
-//	defer writer.Close()
 //
 //	// Write data segments (can be out-of-order)
 //	data1 := []byte("First segment")
@@ -44,15 +43,18 @@
 //	}
 //
 //	// Finalize with attributes and options
-//	finalBytes, manifest, err := writer.Finalize(ctx,
-//		WithAttributeValues(attributes),
-//		WithPayloadMimeType("text/plain"),
-//		WithEncryptedMetadata("sensitive metadata"),
+//	result, err := writer.Finalize(ctx,
+//		tdf.WithAttributeValues(attributes),
+//		tdf.WithPayloadMimeType("text/plain"),
+//		tdf.WithEncryptedMetadata("sensitive metadata"),
 //	)
 //	if err != nil {
 //		log.Fatal(err)
 //	}
 //
+//	// result.Data holds the archive's closing bytes; append it after each
+//	// segment's SegmentResult.TDFData, in ascending segment index order.
+//
 // # Initial Attributes and Default KAS at Writer Creation
 //
 // Callers can provide initial attributes and a default KAS when constructing
@@ -70,26 +72,32 @@
 //	}
 //	// Later, Finalize without attributes/KAS uses the initial values.
 //
-// # Segment Overrides at Finalize (Contiguous Prefix)
+// # Segment Overrides at Finalize
+//
+// By default Finalize describes every written segment, ordered by index.
+// WithSegments narrows that to a chosen subset.
 //
-// You can restrict finalization to a contiguous prefix of written segments
-// using `WithSegments([]int{0, 1, ..., K})`. Indices must start at 0 with no
-// gaps or duplicates, and no segments may have been written beyond K.
+// Indices need not be contiguous — a caller mapping S3 multipart uploads
+// onto segments might write 0, 1, 5000, 5001 — but the list must name
+// written segments in ascending index order and may drop only from the end.
+// That is the order a reader concatenates the payload in, so dropping a
+// segment from the middle would shift every later segment's offset and
+// produce an unreadable TDF.
 //
 //	// Write segments 0 and 1
 //	_, _ = writer.WriteSegment(ctx, 0, []byte("part-0"))
 //	_, _ = writer.WriteSegment(ctx, 1, []byte("part-1"))
 //
-//	// Finalize keeping the prefix [0,1]
-//	finalBytes, manifest, err := writer.Finalize(ctx,
-//		tdf.WithSegments([]int{0, 1}),
+//	// Finalize keeping only segment 0
+//	result, err := writer.Finalize(ctx,
+//		tdf.WithSegments([]int{0}),
 //	)
 //	if err != nil {
 //		log.Fatal(err)
 //	}
 //
-// If all segments should be kept, `WithSegments([0..N-1])` is equivalent to
-// the default behavior and is optional.
+// Keeping every written segment is the default, so passing the full list is
+// optional.
 //
 // # Advanced Features
 //
@@ -103,19 +111,28 @@
 //
 // # Architecture
 //
-// The TDF writer uses a two-layer architecture:
+// The TDF writer uses a three-layer architecture:
 //
-//  1. TDF Layer (tdf.Writer): Handles encryption, assertions, and TDF protocol logic
-//  2. Archive Layer (internal/zipstream): Manages ZIP file structure and segment assembly
+//  1. Adapter Layer (tdf.Writer): Maps this package's options onto the stable
+//     writer and supplies multi-KAS ABAC key splitting
+//  2. TDF Layer (sdk.ChunkedWriter): Handles encryption, assertions, and TDF
+//     protocol logic
+//  3. Archive Layer (internal/zipstream): Manages ZIP file structure and
+//     segment assembly
 //
 // This separation enables independent optimization of cryptographic operations
-// and file format handling.
+// and file format handling. Callers who need only a single KAS can skip layer
+// one and use [github.com/opentdf/platform/sdk.NewChunkedWriter] directly.
 //
 // # Thread Safety
 //
-// Writers are safe for concurrent use with proper external synchronization.
-// Individual WriteSegment calls must be serialized, but multiple writers
-// can operate independently.
+// A Writer is safe for concurrent use. [Writer.WriteSegment] may be called
+// from several goroutines at once so long as each targets a distinct segment
+// index; two concurrent calls for the same index are not allowed, and one of
+// them will fail rather than corrupt the archive.
+//
+// Finalize is terminal and takes an exclusive lock, so it must not overlap
+// with any in-flight WriteSegment call.
 //
 // # Performance Characteristics
 //