@x12i/memorix-format 2.2.2 → 2.3.2

package/docs/memorix-format-for-dummies-association-corrections.md

@@ -1,113 +0,0 @@
-# Corrections To Association Guidance In Memorix Format For Dummies
-
-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.
-
----
-
-## Core correction
-
-Association is always **snapshot-first**, then **content by matched snapshot `recordId`**:
-
-```text
-source snapshot (join value from data / identifier / identity)
-  → match target *-snapshots collection
-  → take matched snapshot recordId
-  → fetch discovery / analysis / decisions by record-id link field
-  → copy flat content.data into associated<ObjectType><ContentType>
-```
-
-**Never** join a source snapshot directly to a non-snapshot collection by business keys such as `data.sku`.
-
----
-
-## Chapter-by-chapter fixes
-
-### Cover / Chapter 0 — Vulnerability patch framing
-
-**Incorrect:** The vulnerability patch wires `findings-snapshots` directly to `findings-discovery` / `findings-decisions` by `data.sku`.
-
-**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`.
-
-### Chapter 4 — Core association rules
-
-**Add before naming and payload rules:**
-
-> 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.
-
-### Chapter 5 — Vulnerability discovery/decisions case file (full rewrite)
-
-Replace the direct-join walkthrough with:
-
-1. Read source `findings-snapshots.data.sku`.
-2. Match target `findings-snapshots` by snapshot paths such as `data.sku`, `concept._extIdentifier`, or `identity`.
-3. Take matched target snapshot `recordId`.
-4. Fetch `findings-discovery` / `findings-decisions` by a record-id link field such as `data.sourceRecordId`, `concept._extIdentifier.recordId`, or root `recordId`.
-5. Copy flat `content.data` into `associatedVulnerabilitiesDiscovery` / `associatedVulnerabilitiesDecisions`.
-
-Payload rules for this pilot:
-
-- Flat copied `data` only
-- No nested `data` wrapper
-- No inline `recordId` on items
-- No `_system.association` metadata
-
-### Chapter 9 — Checklist and glossary
-
-**Checklist additions:**
-
-- [ ] Snapshot match collection is `*-snapshots`
-- [ ] Content fetch uses `recordId` link paths, not business-key joins on content
-- [ ] `_system.association.toProperty` refers to the snapshot match path
-
-**Glossary correction:**
-
-| Term | Incorrect PDF usage | Correct definition |
-|------|---------------------|-------------------|
-| Association key | Business field on content collection | Join path on source snapshot used to match target snapshots |
-| Linked collection | Content collection joined directly | Snapshot match collection + optional content collection fetched by `recordId` |
-
----
-
-## Replacement example (vulnerability discovery/decisions)
-
-```markdown
-1. Read source `findings-snapshots.data.sku`.
-2. Match target `findings-snapshots` by snapshot paths such as `data.sku`, `concept._extIdentifier`, or `identity`.
-3. Take matched target snapshot `recordId`.
-4. Fetch `findings-discovery` / `findings-decisions` by a record-id link field such as `data.sourceRecordId`, `concept._extIdentifier.recordId`, or root `recordId`.
-5. Copy flat `content.data` into `associatedVulnerabilitiesDiscovery` / `associatedVulnerabilitiesDecisions`.
-```
-
----
-
-## Incorrect vs correct
-
-| Aspect | Incorrect (PDF Chapter 5) | Correct |
-|--------|---------------------------|---------|
-| 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`) |
-| Phase count | One-phase direct content join | Two-phase: snapshot match, then content fetch |
-| Same-object rule | Exception allowing direct snapshot→content | Same-object still matches snapshots first |
-| Bridge pattern | Implicit direct join | Explicit `match` + `content` in associator rules |
-
----
-
-## Associator rule shape (reference)
-
-```json
-{
-  "sourceJoinPaths": ["data.sku"],
-  "match": {
-    "collection": "findings-snapshots",
-    "joinPaths": ["data.sku", "concept._extIdentifier.sku", "identity", "recordId"]
-  },
-  "content": {
-    "collection": "findings-discovery",
-    "contentType": "discovery",
-    "linkPaths": ["concept._extIdentifier.recordId", "data.sourceRecordId", "recordId"]
-  },
-  "associatedProperty": "associatedVulnerabilitiesDiscovery",
-  "payload": { "format": "v2", "source": "target.data", "includeRecordId": false }
-}
-```
-
-See also: [memorix-pipeline/docs/association-format.md](../memorix-pipeline/docs/association-format.md)