up

docs/dev/merge_semver_playbook.md

@@ -29,6 +29,8 @@ var rule = primitive.ToNormalizedVersionRule(notes: "nvd:CVE-2025-1234");
 // rule => scheme=semver, type=range, min=1.2.3, minInclusive=true, max=2.0.0, maxInclusive=false
 ```
 
+If you omit the optional `notes` argument, `ToNormalizedVersionRule` now falls back to the primitive’s `ConstraintExpression`, ensuring the original comparator expression is preserved for provenance/audit queries.
+
 Emit the resulting rule inside `AffectedPackage.NormalizedVersions` while continuing to populate `AffectedVersionRange.RangeExpression` for backward compatibility.
 
 ## 3. Merge dedupe flow
@@ -97,3 +99,56 @@ Follow the operational checklist in `docs/ops/migrations/SEMVER_STYLE.md`. The s
 - [ ] Confirm integration tests include fixtures with normalized rules and SemVer styles.
 
 For deeper query examples and maintenance tasks, continue with [Normalized Versions Query Guide](mongo_indices.md).
+
+## 8. Storage projection reference
+
+`NormalizedVersionDocumentFactory` copies each normalized rule into MongoDB using the shape below. Use this as a contract when reviewing connector fixtures or diagnosing merge/storage diffs:
+
+```json
+{
+  "packageId": "pkg:npm/example",
+  "packageType": "npm",
+  "scheme": "semver",
+  "type": "range",
+  "style": "range",
+  "min": "1.2.3",
+  "minInclusive": true,
+  "max": "2.0.0",
+  "maxInclusive": false,
+  "value": null,
+  "notes": "ghsa:GHSA-xxxx-yyyy",
+  "decisionReason": "ghsa-precedence-over-nvd",
+  "constraint": ">= 1.2.3 < 2.0.0",
+  "source": "ghsa",
+  "recordedAt": "2025-10-11T00:00:00Z"
+}
+```
+
+For distro-specific ranges (`nevra`, `evr`) the same envelope applies with `scheme` switched accordingly. Example:
+
+```json
+{
+  "packageId": "bash",
+  "packageType": "rpm",
+  "scheme": "nevra",
+  "type": "range",
+  "style": "range",
+  "min": "0:4.4.18-2.el7",
+  "minInclusive": true,
+  "max": "0:4.4.20-1.el7",
+  "maxInclusive": false,
+  "value": null,
+  "notes": "redhat:RHSA-2025:1234",
+  "decisionReason": "rhel-priority-over-nvd",
+  "constraint": "<= 0:4.4.20-1.el7",
+  "source": "redhat",
+  "recordedAt": "2025-10-11T00:00:00Z"
+}
+```
+
+If a new scheme is required (for example, `apple.build` or `ios.semver`), raise it with the Models team before emitting documents so merge comparers and hashing logic can incorporate the change deterministically.
+
+## 9. Observability signals
+
+- `feedser.merge.normalized_rules` (counter, tags: `package_type`, `scheme`) – increments once per normalized rule retained after precedence merge.
+- `feedser.merge.normalized_rules_missing` (counter, tags: `package_type`) – increments when a merged package still carries version ranges but no normalized rules; watch for spikes to catch connectors that have not emitted normalized arrays yet.