@x12i/memorix-retrieval 1.20.0 → 1.22.0

package/README.md

@@ -289,6 +289,62 @@ const page = await fetchMemorixSliceRecords(client, {
 });
 ```
 
+## Record display names
+
+Human-readable titles for operators come from **`record.concept.name`** on stored documents (see [MEMORIX-DATABASE-CONVENTIONS.md](./docs/MEMORIX-DATABASE-CONVENTIONS.md)). Memorix read-tier APIs resolve display names centrally — hosts must not scan top-level `id`, `name`, or `data.*` fields.
+
+```typescript
+import { resolveMemorixRecordDisplayName } from "@x12i/memorix-retrieval";
+
+const displayName = resolveMemorixRecordDisplayName(record, {
+  preferredLocale: "en", // optional; for localized concept.name objects
+});
+// string | undefined — never falls back to record id or identity fields
+```
+
+**Supported `concept.name` shapes:** plain string, string array (first non-empty entry), localized object (`{ en: "...", he: "..." }`).
+
+**List and item responses** include optional top-level `displayName` (and list rows also expose `recordId` when resolvable):
+
+- `fetchMemorixList` / `fetchMemorixListForEntity` → `rows[].displayName`
+- `fetchMemorixItem` / `fetchMemorixItemForEntity` → `displayName`
+- `listMemorixEntityContentTypeDocuments` → `documents[].displayName`
+
+When `concept.name` is absent, `displayName` is omitted. Show the record id separately for disambiguation — do not substitute it as the title.
+
+### Easy retrieval helpers
+
+Use these when you need identity + display name without re-implementing Memorix rules:
+
+```typescript
+import {
+  fetchMemorixRecordInfoForEntity,
+  resolveMemorixRecordInfo,
+  resolveMemorixRecordInfoFromRow,
+  resolveMemorixRecordInfoFromItem,
+  formatMemorixRecordLabel,
+} from "@x12i/memorix-retrieval";
+
+// One call: lookup by entity + recordId / entityId / eventId / knowledgeId
+const info = await fetchMemorixRecordInfoForEntity(client, {
+  entityName: "vulnerability-groups",
+  recordId: "69d216ed358778e93215788d",
+});
+// → { recordId, displayName?, entityId?, identityField?, identityValue? }
+
+// From list rows (already stamped with displayName)
+const fromRow = resolveMemorixRecordInfoFromRow(listRow);
+
+// From item responses
+const fromItem = resolveMemorixRecordInfoFromItem(itemResponse);
+
+// Picker / journal label — name when present, else id
+const label = formatMemorixRecordLabel(info);
+const withSuffix = formatMemorixRecordLabel(info, { includeIdSuffix: true });
+```
+
+**Search:** `memorixLabelSearchFilter` (used by raw entity reads) includes `concept.name` for string-valued names. Localized-object search is best-effort on the `concept.name` path only.
+
 ## Record identity
 
 ```typescript

package/catalox-seeds/inputs/entity-descriptors/vulnerabilities.json

@@ -384,27 +384,6 @@
         "xdrAgentStatus",
         "potentialImpactLevel"
       ]
-    },
-    "vulnerabilityGroup": {
-      "targetEntity": "variabilities-groups",
-      "type": "manyToOne",
-      "source": {
-        "contentType": "snapshots",
-        "path": "sourceFacts.values.pluginId.rawValue"
-      },
-      "target": {
-        "contentType": "snapshots",
-        "path": "sourceFacts.values.plugin_id.rawValue"
-      },
-      "defaultMode": "extendFields",
-      "targetFields": [
-        "groupId",
-        "pluginName",
-        "severity",
-        "affectedEntitiesCount",
-        "riskLevel",
-        "priorityScore"
-      ]
     }
   }
 }

package/catalox-seeds/inputs/manifest.json

@@ -5,42 +5,35 @@
   "catalogs": {
     "memorix-object-type-descriptors": [
       "assets",
-      "vulnerabilities",
-      "variabilities-groups"
+      "topology-subnets",
+      "vulnerabilities"
     ],
     "memorix-list-descriptors": [
       "assets-main-list",
+      "topology-subnets-main-list",
       "vulnerabilities-main-list",
       "critical-vulnerabilities-list",
-      "variabilities-groups-main-list",
       "memorix-workspace-records-list"
     ],
     "memorix-item-descriptors": [
       "asset-detail-item",
-      "vulnerability-detail-item",
-      "variabilities-group-detail-item"
+      "topology-subnet-detail-item",
+      "vulnerability-detail-item"
     ]
   },
   "files": [
     "entity-descriptors/assets.json",
-    "entity-descriptors/variabilities-groups.json",
+    "entity-descriptors/topology-subnets.json",
     "entity-descriptors/vulnerabilities.json",
     "item-descriptors/asset-detail-item.json",
-    "item-descriptors/variabilities-group-detail-item.json",
+    "item-descriptors/topology-subnet-detail-item.json",
     "item-descriptors/vulnerability-detail-item.json",
     "list-descriptors/assets-main-list.json",
     "list-descriptors/critical-vulnerabilities-list.json",
-    "list-descriptors/variabilities-groups-main-list.json",
+    "list-descriptors/topology-subnets-main-list.json",
     "list-descriptors/vulnerabilities-main-list.json",
     "list-descriptors/memorix-workspace-records-list.json",
     "memorix-catalog-ids.json",
-    "memorix-descriptors.bundle.json",
-    "memorix-object-type-descriptors.catalog.json",
-    "memorix-object-type-descriptors.items.json",
-    "memorix-item-descriptors.catalog.json",
-    "memorix-item-descriptors.items.json",
-    "memorix-list-descriptors.catalog.json",
-    "memorix-list-descriptors.items.json",
     "scope.json"
   ]
 }

package/catalox-seeds/memorix-retrieval-descriptors.manifest.json

@@ -2,7 +2,7 @@
   "presetVersion": 1,
   "id": "memorix-retrieval-descriptors",
   "name": "Memorix retrieval descriptors",
-  "description": "Entity, list, and item descriptors for @x12i/memorix-retrieval (from catalox-seeds/inputs/). assets and variabilities-groups target memorix-entities; vulnerabilities target memorix-events. All items share scope.domains/network+vulnerabilities and scope.agents/neo.",
+  "description": "Entity, list, and item descriptors for @x12i/memorix-retrieval (from catalox-seeds/inputs/). assets and topology-subnets target memorix-entities; vulnerabilities target memorix-events. All items share scope.domains/network+vulnerabilities and scope.agents/neo.",
   "catalogs": [
     {
       "catalogId": "memorix-object-type-descriptors",
@@ -721,322 +721,6 @@
         "objectType": "topology-subnets"
       }
     },
-    {
-      "catalogId": "memorix-object-type-descriptors",
-      "scope": {
-        "domains": [
-          "network",
-          "vulnerabilities"
-        ],
-        "agents": [
-          "neo"
-        ]
-      },
-      "data": {
-        "id": "variabilities-groups",
-        "defaultListDescriptorId": "variabilities-groups-main-list",
-        "defaultItemDescriptorId": "variabilities-group-detail-item",
-        "target": "entity",
-        "collectionPrefix": "variabilities-groups",
-        "identity": {
-          "allowedIdFields": [
-            "identity.recordId",
-            "identity.targetId"
-          ],
-          "requiredExactlyOne": true,
-          "defaultIdField": "identity.recordId"
-        },
-        "defaults": {
-          "canonicalContentType": "snapshots",
-          "dataRoot": "data",
-          "effectiveDatePath": "lifecycle.capturedAt",
-          "fallbackEffectiveDatePaths": [
-            "capturedAt",
-            "snapshot.capturedAt",
-            "data.enrichedAt",
-            "data.enrichment.enrichedAt"
-          ]
-        },
-        "contentTypes": {
-          "snapshots": {
-            "postfix": "snapshots",
-            "collection": "variabilities-groups-snapshots",
-            "dataRoot": "data",
-            "isCanonical": true,
-            "effectiveDatePath": "lifecycle.capturedAt",
-            "fallbackEffectiveDatePaths": [
-              "capturedAt",
-              "snapshot.capturedAt",
-              "data.enrichedAt",
-              "data.enrichment.enrichedAt"
-            ]
-          }
-        },
-        "properties": {
-          "groupId": {
-            "label": "Group ID",
-            "source": {
-              "contentType": "snapshots",
-              "path": "sourceFacts.values.id.rawValue"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "string"
-          },
-          "type": {
-            "label": "Type",
-            "source": {
-              "contentType": "snapshots",
-              "path": "sourceFacts.values.type.rawValue"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "string"
-          },
-          "pluginId": {
-            "label": "Plugin ID",
-            "source": {
-              "contentType": "snapshots",
-              "path": "sourceFacts.values.plugin_id.rawValue"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "number"
-          },
-          "pluginName": {
-            "label": "Plugin Name",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.name"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "string"
-          },
-          "pluginFamily": {
-            "label": "Plugin Family",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.vulnerability_family"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "string"
-          },
-          "severity": {
-            "label": "Severity",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.severity"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "string"
-          },
-          "affectedEntities": {
-            "label": "Affected Entities",
-            "source": {
-              "contentType": "snapshots",
-              "path": "associatedData.affectedAssets"
-            },
-            "humanReadable": true,
-            "sortable": false,
-            "filterable": true,
-            "list": false,
-            "item": true,
-            "valueType": "array"
-          },
-          "affectedEntitiesCount": {
-            "label": "Affected Entities Count",
-            "source": {
-              "contentType": "snapshots",
-              "path": "associatedData.affectedAssets"
-            },
-            "humanReadable": true,
-            "sortable": false,
-            "filterable": false,
-            "list": true,
-            "item": true,
-            "valueType": "array",
-            "format": "count"
-          },
-          "source": {
-            "label": "Source",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.source"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": false,
-            "item": true,
-            "valueType": "string"
-          },
-          "cveId": {
-            "label": "CVE",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.cveId"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "string"
-          },
-          "riskLevel": {
-            "label": "Risk Level",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.enrichment.riskLevel"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "string"
-          },
-          "priorityScore": {
-            "label": "Priority Score",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.enrichment.priorityScore"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "number"
-          },
-          "compositeScore": {
-            "label": "Composite Score",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.enrichment.compositeScore"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "number"
-          },
-          "epss": {
-            "label": "EPSS",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.enrichment.epss.epss"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "number"
-          },
-          "knownExploited": {
-            "label": "Known Exploited",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.enrichment.kev.isKnownExploited"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "boolean"
-          },
-          "cvssBaseScore": {
-            "label": "CVSS Base Score",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.enrichment.cvss.baseScore"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": true,
-            "item": true,
-            "valueType": "number"
-          },
-          "cvssVector": {
-            "label": "CVSS Vector",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.enrichment.cvss.cvssVector"
-            },
-            "humanReadable": true,
-            "sortable": false,
-            "filterable": true,
-            "list": false,
-            "item": true,
-            "valueType": "string"
-          },
-          "enrichedAt": {
-            "label": "Enriched At",
-            "source": {
-              "contentType": "snapshots",
-              "path": "data.enrichedAt"
-            },
-            "humanReadable": true,
-            "sortable": true,
-            "filterable": true,
-            "list": false,
-            "item": true,
-            "valueType": "datetime"
-          }
-        },
-        "relations": {
-          "groupVulnerabilities": {
-            "type": "oneToMany",
-            "source": {
-              "contentType": "snapshots",
-              "path": "sourceFacts.values.plugin_id.rawValue"
-            },
-            "target": {
-              "contentType": "snapshots",
-              "path": "sourceFacts.values.pluginId.rawValue"
-            },
-            "defaultMode": "array",
-            "defaultArrayProperty": "vulnerabilities",
-            "targetFields": [
-              "vulnerabilityId",
-              "assetIp",
-              "pluginName",
-              "severity",
-              "riskLevel",
-              "priorityScore"
-            ],
-            "targetObjectType": "vulnerabilities"
-          }
-        },
-        "schemaVersion": "memorix.objectTypeDescriptor.v2",
-        "objectType": "variabilities-groups"
-      }
-    },
     {
       "catalogId": "memorix-object-type-descriptors",
       "scope": {
@@ -1433,27 +1117,6 @@
               "potentialImpactLevel"
             ],
             "targetObjectType": "assets"
-          },
-          "vulnerabilityGroup": {
-            "type": "manyToOne",
-            "source": {
-              "contentType": "snapshots",
-              "path": "sourceFacts.values.pluginId.rawValue"
-            },
-            "target": {
-              "contentType": "snapshots",
-              "path": "sourceFacts.values.plugin_id.rawValue"
-            },
-            "defaultMode": "extendFields",
-            "targetFields": [
-              "groupId",
-              "pluginName",
-              "severity",
-              "affectedEntitiesCount",
-              "riskLevel",
-              "priorityScore"
-            ],
-            "targetObjectType": "variabilities-groups"
           }
         },
         "schemaVersion": "memorix.objectTypeDescriptor.v2",
@@ -1921,61 +1584,6 @@
         "target": "event"
       }
     },
-    {
-      "catalogId": "memorix-list-descriptors",
-      "scope": {
-        "domains": [
-          "network",
-          "vulnerabilities"
-        ],
-        "agents": [
-          "neo"
-        ]
-      },
-      "data": {
-        "id": "variabilities-groups-main-list",
-        "entity": "variabilities-groups",
-        "title": "Vulnerability Groups",
-        "leadingContentType": "snapshots",
-        "pagination": {
-          "enabled": true,
-          "defaultLimit": 50,
-          "maxLimit": 200
-        },
-        "filters": [],
-        "fields": [
-          "groupId",
-          "pluginName",
-          "pluginFamily",
-          "severity",
-          "affectedEntitiesCount",
-          "cveId",
-          "riskLevel",
-          "priorityScore",
-          "epss",
-          "knownExploited"
-        ],
-        "extensions": [],
-        "includeRelations": [],
-        "allowedSorts": [
-          "groupId",
-          "pluginId",
-          "pluginName",
-          "pluginFamily",
-          "severity",
-          "riskLevel",
-          "priorityScore",
-          "epss",
-          "knownExploited",
-          "cvssBaseScore"
-        ],
-        "defaultSort": {
-          "property": "priorityScore",
-          "direction": "desc"
-        },
-        "allowSortDrivenLeadingOverride": false
-      }
-    },
     {
       "catalogId": "memorix-list-descriptors",
       "scope": {
@@ -2369,105 +1977,6 @@
         }
       }
     },
-    {
-      "catalogId": "memorix-item-descriptors",
-      "scope": {
-        "domains": [
-          "network",
-          "vulnerabilities"
-        ],
-        "agents": [
-          "neo"
-        ]
-      },
-      "data": {
-        "id": "variabilities-group-detail-item",
-        "entity": "variabilities-groups",
-        "title": "Vulnerability Group Detail",
-        "identity": {
-          "idField": "identity.recordId"
-        },
-        "contentTypes": [
-          {
-            "contentType": "snapshots",
-            "required": true,
-            "multiMatch": {
-              "strategy": "last",
-              "effectiveDatePath": "lifecycle.capturedAt",
-              "fallbackEffectiveDatePaths": [
-                "capturedAt",
-                "snapshot.capturedAt",
-                "data.enrichedAt",
-                "data.enrichment.enrichedAt"
-              ]
-            }
-          }
-        ],
-        "sections": [
-          {
-            "id": "summary",
-            "title": "Summary",
-            "fields": [
-              "groupId",
-              "type",
-              "pluginId",
-              "pluginName",
-              "pluginFamily",
-              "severity",
-              "cveId",
-              "source"
-            ]
-          },
-          {
-            "id": "affectedEntities",
-            "title": "Affected Entities",
-            "fields": [
-              "affectedEntities",
-              "affectedEntitiesCount"
-            ]
-          },
-          {
-            "id": "risk",
-            "title": "Risk",
-            "fields": [
-              "riskLevel",
-              "priorityScore",
-              "compositeScore"
-            ]
-          },
-          {
-            "id": "threatIntelligence",
-            "title": "Threat Intelligence",
-            "fields": [
-              "epss",
-              "knownExploited",
-              "cvssBaseScore",
-              "cvssVector",
-              "enrichedAt"
-            ]
-          }
-        ],
-        "includeRelations": [
-          {
-            "relation": "groupVulnerabilities",
-            "mode": "array",
-            "arrayProperty": "vulnerabilities",
-            "limit": 200,
-            "fields": [
-              "vulnerabilityId",
-              "assetIp",
-              "pluginName",
-              "severity",
-              "riskLevel",
-              "priorityScore"
-            ]
-          }
-        ],
-        "content": {
-          "allowed": false
-        }
-      }
-    },
     {
       "catalogId": "memorix-item-descriptors",
       "scope": {

package/dist/client/types.d.ts

@@ -90,6 +90,10 @@ export type FetchMemorixListRequest = {
     auditRead?: boolean;
     includeSourceRefs?: boolean;
 };
+export type MemorixRecordDisplayFields = {
+    recordId?: string;
+    displayName?: string;
+};
 export type FetchMemorixListResponse = {
     listId: string;
     entity: string;
@@ -106,7 +110,7 @@ export type FetchMemorixListResponse = {
         direction: "asc" | "desc";
         contentType: string;
     };
-    rows: Array<Record<string, unknown>>;
+    rows: Array<Record<string, unknown> & MemorixRecordDisplayFields>;
     issues?: import("../errors/issues.js").MemorixRetrievalIssue[];
     source?: import("../runtime/source-provenance.js").MemorixRuntimeSourceRef;
     sources?: import("../runtime/source-provenance.js").MemorixRuntimeSourceRef[];
@@ -191,6 +195,7 @@ export type FetchMemorixItemResponse = {
     entityId?: string;
     eventId?: string;
     knowledgeId?: string;
+    displayName?: string;
     sections: Array<{
         id: string;
         title: string;