Resolve Concelier/Excititor merge conflicts

docs/artifacts/bom-index/README.md

@@ -0,0 +1,50 @@
+# StellaOps BOM Index (`bom-index@1`)
+
+The BOM index is a deterministic, offline-friendly sidecar that accelerates queries for
+layer-to-component membership and entrypoint usage. It is emitted alongside CycloneDX
+SBOMs and consumed by Scheduler/Notify services.
+
+## File Layout
+
+Binary little-endian encoding, organised as the following sections:
+
+1. **Header**
+   - `magic` (`byte[7]`): ASCII `"BOMIDX1"` identifier.
+   - `version` (`uint16`): current value `1`.
+   - `flags` (`uint16`): bit `0` set when entrypoint usage bitmaps are present.
+   - `imageDigestLength` (`uint16`) + UTF-8 digest string (e.g. `sha256:...`).
+   - `generatedAt` (`int64`): microseconds since Unix epoch.
+   - `layerCount` (`uint32`), `componentCount` (`uint32`), `entrypointCount` (`uint32`).
+
+2. **Layer Table**
+   - For each layer: `length` (`uint16`) + UTF-8 layer digest (canonical order, base image → top layer).
+
+3. **Component Table**
+   - For each component: `length` (`uint16`) + UTF-8 identity (CycloneDX purl when available, otherwise canonical key).
+
+4. **Component ↦ Layer Bitmaps**
+   - For each component (matching table order):
+     - `bitmapLength` (`uint32`).
+     - Roaring bitmap payload (`Collections.Special.RoaringBitmap.Serialize`) encoding layer indexes that introduce or retain the component.
+
+5. **Entrypoint Table** *(optional; present when `flags & 0x1 == 1`)*
+   - For each unique entrypoint/launcher string: `length` (`uint16`) + UTF-8 value (sorted ordinally).
+
+6. **Component ↦ Entrypoint Bitmaps** *(optional)*
+   - For each component: roaring bitmap whose set bits reference entrypoint indexes used by EntryTrace. Empty bitmap (`length == 0`) indicates the component is not part of any resolved entrypoint closure.
+
+## Determinism Guarantees
+
+* Layer, component, and entrypoint tables are strictly ordered (base → top layer, lexicographically for components and entrypoints).
+* Roaring bitmaps are optimised prior to serialisation and always produced from sorted indexes.
+* Header timestamp is normalised to microsecond precision using UTC.
+
+## Sample
+
+`sample-index.bin` is generated from the integration fixture used in unit tests. It contains:
+
+* 2 layers: `sha256:layer1`, `sha256:layer2`.
+* 3 components: `pkg:npm/a`, `pkg:npm/b`, `pkg:npm/c`.
+* Entrypoint bitmaps for `/app/start.sh` and `/app/init.sh`.
+
+The sample can be decoded with the `BomIndexBuilder` unit tests or any RoaringBitmap implementation compatible with `Collections.Special.RoaringBitmap`.