more platform

projection/doc.go

@@ -0,0 +1,27 @@
+// Package projection is the domain-neutral substrate for the "snapshot stream +
+// local index" seam: one authoritative producer publishes a framed
+// begin → chunk* → end snapshot (plus per-batch deltas) on the bus, and N
+// receivers each assemble their OWN cold-start-ready, mmap-backed .bin index
+// from it. No shared volume; each consumer is independently eventually
+// consistent.
+//
+// It was extracted from platform/catalog (which now re-exports these types for
+// its Projection wire shape) so other domains can ride the same rails without
+// depending on catalog. The pieces:
+//
+//   - SnapshotWriter[T] / SnapshotReader[T] (snapshot.go) — the value-agnostic
+//     key→blob .bin format: sorted records, binary-search Get, full-walk Scan,
+//     mmap on Unix. Generic over the stored type T.
+//   - SnapshotHolder[T] (manager.go) — race-free atomic hot-reload of a reader
+//     under concurrent Get/Scan, with a drain-grace close-batching reaper.
+//   - Store[W, T] (store.go) — the consumer state machine: snapshot assembly,
+//     epoch gating, same-epoch delta overlay (with delete tombstones), and the
+//     completeness guard. Generic over the WIRE type W (decoded by a
+//     domain-supplied Decoder) and the STORED type T (projected by a Transform).
+//   - The bus framing contract (framing.go) — Meta* keys, snapshot phases, and
+//     the decoded Update[W] shape.
+//
+// The framing is fixed and shared; the on-the-wire payload schema is the
+// domain's own concern, bridged by Decoder[W]. See
+// docs/plan-projectionstore-generalization.md for why this boundary exists.
+package projection