@x12i/memorix-format 2.2.2 → 2.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1,113 +0,0 @@
|
|
|
1
|
-
# Corrections To Association Guidance In Memorix Format For Dummies
|
|
2
|
-
|
|
3
|
-
This document records required fixes to association guidance in `ebooks/memorix-format-for-dummies.pdf`. The PDF's **Chapter 5** (vulnerability discovery/decisions case file) teaches a **direct content join** model that is incorrect.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## Core correction
|
|
8
|
-
|
|
9
|
-
Association is always **snapshot-first**, then **content by matched snapshot `recordId`**:
|
|
10
|
-
|
|
11
|
-
```text
|
|
12
|
-
source snapshot (join value from data / identifier / identity)
|
|
13
|
-
→ match target *-snapshots collection
|
|
14
|
-
→ take matched snapshot recordId
|
|
15
|
-
→ fetch discovery / analysis / decisions by record-id link field
|
|
16
|
-
→ copy flat content.data into associated<ObjectType><ContentType>
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
**Never** join a source snapshot directly to a non-snapshot collection by business keys such as `data.sku`.
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## Chapter-by-chapter fixes
|
|
24
|
-
|
|
25
|
-
### Cover / Chapter 0 — Vulnerability patch framing
|
|
26
|
-
|
|
27
|
-
**Incorrect:** The vulnerability patch wires `findings-snapshots` directly to `findings-discovery` / `findings-decisions` by `data.sku`.
|
|
28
|
-
|
|
29
|
-
**Correct:** The patch enriches `findings-snapshots` using snapshot-mediated resolution: match snapshots first (including same-object `findings-snapshots`), then fetch discovery/decisions content linked to the matched snapshot `recordId`.
|
|
30
|
-
|
|
31
|
-
### Chapter 4 — Core association rules
|
|
32
|
-
|
|
33
|
-
**Add before naming and payload rules:**
|
|
34
|
-
|
|
35
|
-
> Record-to-record association always resolves through snapshots. Non-snapshot collections (`discovery`, `analysis`, `decisions`, …) are fetched only after a snapshot match yields a target `recordId`. Associated content is never the source of truth for the link.
|
|
36
|
-
|
|
37
|
-
### Chapter 5 — Vulnerability discovery/decisions case file (full rewrite)
|
|
38
|
-
|
|
39
|
-
Replace the direct-join walkthrough with:
|
|
40
|
-
|
|
41
|
-
1. Read source `findings-snapshots.data.sku`.
|
|
42
|
-
2. Match target `findings-snapshots` by snapshot paths such as `data.sku`, `concept._extIdentifier`, or `identity`.
|
|
43
|
-
3. Take matched target snapshot `recordId`.
|
|
44
|
-
4. Fetch `findings-discovery` / `findings-decisions` by a record-id link field such as `data.sourceRecordId`, `concept._extIdentifier.recordId`, or root `recordId`.
|
|
45
|
-
5. Copy flat `content.data` into `associatedVulnerabilitiesDiscovery` / `associatedVulnerabilitiesDecisions`.
|
|
46
|
-
|
|
47
|
-
Payload rules for this pilot:
|
|
48
|
-
|
|
49
|
-
- Flat copied `data` only
|
|
50
|
-
- No nested `data` wrapper
|
|
51
|
-
- No inline `recordId` on items
|
|
52
|
-
- No `_system.association` metadata
|
|
53
|
-
|
|
54
|
-
### Chapter 9 — Checklist and glossary
|
|
55
|
-
|
|
56
|
-
**Checklist additions:**
|
|
57
|
-
|
|
58
|
-
- [ ] Snapshot match collection is `*-snapshots`
|
|
59
|
-
- [ ] Content fetch uses `recordId` link paths, not business-key joins on content
|
|
60
|
-
- [ ] `_system.association.toProperty` refers to the snapshot match path
|
|
61
|
-
|
|
62
|
-
**Glossary correction:**
|
|
63
|
-
|
|
64
|
-
| Term | Incorrect PDF usage | Correct definition |
|
|
65
|
-
|------|---------------------|-------------------|
|
|
66
|
-
| Association key | Business field on content collection | Join path on source snapshot used to match target snapshots |
|
|
67
|
-
| Linked collection | Content collection joined directly | Snapshot match collection + optional content collection fetched by `recordId` |
|
|
68
|
-
|
|
69
|
-
---
|
|
70
|
-
|
|
71
|
-
## Replacement example (vulnerability discovery/decisions)
|
|
72
|
-
|
|
73
|
-
```markdown
|
|
74
|
-
1. Read source `findings-snapshots.data.sku`.
|
|
75
|
-
2. Match target `findings-snapshots` by snapshot paths such as `data.sku`, `concept._extIdentifier`, or `identity`.
|
|
76
|
-
3. Take matched target snapshot `recordId`.
|
|
77
|
-
4. Fetch `findings-discovery` / `findings-decisions` by a record-id link field such as `data.sourceRecordId`, `concept._extIdentifier.recordId`, or root `recordId`.
|
|
78
|
-
5. Copy flat `content.data` into `associatedVulnerabilitiesDiscovery` / `associatedVulnerabilitiesDecisions`.
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
---
|
|
82
|
-
|
|
83
|
-
## Incorrect vs correct
|
|
84
|
-
|
|
85
|
-
| Aspect | Incorrect (PDF Chapter 5) | Correct |
|
|
86
|
-
|--------|---------------------------|---------|
|
|
87
|
-
| Join path | `findings-snapshots.data.sku` → `findings-discovery.data.sku` | `findings-snapshots.data.sku` → `findings-snapshots` (snapshot match) → `recordId` → `findings-discovery` (by `concept._extIdentifier.recordId`) |
|
|
88
|
-
| Phase count | One-phase direct content join | Two-phase: snapshot match, then content fetch |
|
|
89
|
-
| Same-object rule | Exception allowing direct snapshot→content | Same-object still matches snapshots first |
|
|
90
|
-
| Bridge pattern | Implicit direct join | Explicit `match` + `content` in associator rules |
|
|
91
|
-
|
|
92
|
-
---
|
|
93
|
-
|
|
94
|
-
## Associator rule shape (reference)
|
|
95
|
-
|
|
96
|
-
```json
|
|
97
|
-
{
|
|
98
|
-
"sourceJoinPaths": ["data.sku"],
|
|
99
|
-
"match": {
|
|
100
|
-
"collection": "findings-snapshots",
|
|
101
|
-
"joinPaths": ["data.sku", "concept._extIdentifier.sku", "identity", "recordId"]
|
|
102
|
-
},
|
|
103
|
-
"content": {
|
|
104
|
-
"collection": "findings-discovery",
|
|
105
|
-
"contentType": "discovery",
|
|
106
|
-
"linkPaths": ["concept._extIdentifier.recordId", "data.sourceRecordId", "recordId"]
|
|
107
|
-
},
|
|
108
|
-
"associatedProperty": "associatedVulnerabilitiesDiscovery",
|
|
109
|
-
"payload": { "format": "v2", "source": "target.data", "includeRecordId": false }
|
|
110
|
-
}
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
See also: [memorix-pipeline/docs/association-format.md](../memorix-pipeline/docs/association-format.md)
|