[wip] introduce BuildLibrary and make overlay first-class

masque/file/gdsii_lazy.py

@@ -1,9 +1,18 @@
 """
-Source-backed lazy GDSII reader using the pure-python klamath path.
+Classic source-backed lazy GDSII reader built on the pure-python klamath path.
 
-This module mirrors the lazy Arrow reader's interface closely enough to share
-the same overlay and ports-import helpers, while still materializing cells
-through the classic `gdsii` decoder.
+This module provides the non-Arrow half of Masque's lazy GDS architecture:
+
+- `GdsLibrarySource` scans a GDS stream once to discover library metadata,
+  struct order, and child edges without materializing every cell.
+- cells are materialized on demand through the classic `gdsii` decoder
+  whenever a caller indexes the lazy view
+- the source can be wrapped in `PortsLibraryView` or merged through
+  `OverlayLibrary`, both of which live in `gdsii_lazy_core`
+
+The public surface intentionally parallels `gdsii_lazy_arrow` closely so that
+callers can swap between the classic and Arrow-backed implementations with
+minimal changes.
 """
 from __future__ import annotations
 
@@ -36,6 +45,7 @@ logger = logging.getLogger(__name__)
 
 @dataclass
 class _SourceHandle:
+    """ Owns the underlying stream and any companion file handle for a source. """
     path: pathlib.Path | None
     stream: IO[bytes]
     handle: IO[bytes] | None = None
@@ -49,6 +59,7 @@ class _SourceHandle:
 
 @dataclass(frozen=True)
 class _CellScan:
+    """ Scan-time metadata for one cell in the source stream. """
     offset: int
     children: set[str]
 
@@ -107,6 +118,10 @@ class GdsLibrarySource(ILibraryView):
 
     Cells are scanned once up front to discover order and child edges, then
     materialized one at a time through the classic `gdsii.read_elements` path.
+
+    The source owns the stream lifetime, preserves on-disk ordering through
+    `source_order()`, and answers graph queries from scan metadata whenever
+    possible so callers can inspect hierarchy without forcing a full load.
     """
 
     def __init__(