@x12i/memorix-retrieval 1.9.2 → 1.11.0

package/metadata/log-diagnostics.json

@@ -0,0 +1,182 @@
+{
+  "MONGO_CONNECTION_FAILED": {
+    "defaultLevel": "error",
+    "title": "MongoDB connection failed",
+    "impact": "Retrieval reads cannot run until Mongo is reachable.",
+    "possibleCauses": [
+      "MONGO_URI or MONGO_CONNECTION_STRING is missing or invalid.",
+      "MongoDB is not running or not reachable from this host.",
+      "Network or TLS configuration blocks the connection."
+    ],
+    "remediation": [
+      "Verify MONGO_URI is set and points to a live cluster.",
+      "Check Mongo connectivity from this host.",
+      "Review TLS/auth settings on the connection string."
+    ],
+    "retryable": true,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "UNKNOWN_ENTITY_DESCRIPTOR": {
+    "defaultLevel": "error",
+    "title": "Entity descriptor not found in Catalox",
+    "impact": "Entity-scoped reads and composition cannot resolve schema or collection bindings.",
+    "possibleCauses": [
+      "The descriptor id is misspelled or not seeded in Catalox.",
+      "CATALOX_APP_ID or MEMORIX_APP_ID does not match the seeded app namespace.",
+      "Catalog permissions block read access to entity descriptors."
+    ],
+    "remediation": [
+      "Confirm the entity descriptor id exists in the entity-descriptors catalog.",
+      "Run catalox seed ensure/apply for memorix-retrieval descriptors.",
+      "Verify Catalox context appId and actor permissions."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "UNKNOWN_LIST": {
+    "defaultLevel": "error",
+    "title": "List descriptor not found in Catalox",
+    "impact": "List fetch cannot resolve fields, filters, or pagination driver.",
+    "possibleCauses": [
+      "The listId is not present in the list-descriptors catalog.",
+      "Descriptor seed was not applied for this environment.",
+      "App namespace or catalog access does not match the request."
+    ],
+    "remediation": [
+      "Verify listId in Catalox list-descriptors catalog.",
+      "Apply memorix-retrieval Catalox seeds.",
+      "Check appId and Catalox read permissions."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "UNKNOWN_ITEM": {
+    "defaultLevel": "error",
+    "title": "Item descriptor not found in Catalox",
+    "impact": "Item composition cannot resolve sections or field bindings.",
+    "possibleCauses": [
+      "The item descriptor id is missing from Catalox.",
+      "Seeds were not applied or target the wrong app namespace.",
+      "Catalog read is blocked by Catalox policy."
+    ],
+    "remediation": [
+      "Verify item descriptor id in Catalox item-descriptors catalog.",
+      "Run npm run catalox:seed:ensure.",
+      "Check MEMORIX_APP_ID / CATALOX_APP_ID alignment."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "DESCRIPTOR_MAPPING_BLOCKED": {
+    "defaultLevel": "error",
+    "title": "Descriptor mapping blocked by Catalox",
+    "impact": "Retrieval cannot load the descriptor payload required for reads.",
+    "possibleCauses": [
+      "Catalox mapping policy blocks this descriptor for the current actor.",
+      "Descriptor bindings are incomplete or restricted.",
+      "Super-admin or service context is missing where required."
+    ],
+    "remediation": [
+      "Review Catalox mapping policy for the descriptor catalog item.",
+      "Use an actor/context with permission to read mapped descriptors.",
+      "Inspect Catalox seed bindings for the descriptor."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "medium"
+  },
+  "INVALID_DESCRIPTOR": {
+    "defaultLevel": "error",
+    "title": "Descriptor payload failed validation",
+    "impact": "Retrieval refuses to use an invalid descriptor to avoid incorrect reads.",
+    "possibleCauses": [
+      "Descriptor JSON in Catalox is missing required fields.",
+      "Descriptor shape drifted from memorix-descriptors schema.",
+      "Catalog item data was corrupted or partially written."
+    ],
+    "remediation": [
+      "Validate the descriptor JSON against memorix-descriptors types.",
+      "Re-seed or fix the catalog item in Catalox.",
+      "Compare failing field paths in the error message."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "INVALID_FILTER": {
+    "defaultLevel": "error",
+    "title": "Runtime or descriptor filter is invalid",
+    "impact": "The list or slice query cannot be compiled safely to Mongo.",
+    "possibleCauses": [
+      "An unsupported filter operator was supplied.",
+      "advancedMongo filter is missing a mongo object.",
+      "Filter references an unknown field or unsafe Mongo operator."
+    ],
+    "remediation": [
+      "Review filter operator and field names against the entity descriptor.",
+      "Ensure advancedMongo filters include a valid mongo clause.",
+      "Remove unsupported operators from the request."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "MISSING_DESCRIPTOR": {
+    "defaultLevel": "warn",
+    "title": "Required descriptor reference is missing",
+    "impact": "Partial data may be returned or a field may be omitted from the composed view.",
+    "possibleCauses": [
+      "A relation or extension references a descriptor that is not loaded.",
+      "Default descriptor resolution failed for the entity.",
+      "Catalog item was deleted or not seeded."
+    ],
+    "remediation": [
+      "Verify related descriptor ids in Catalox catalogs.",
+      "Check entity default list/item descriptor configuration.",
+      "Re-run descriptor seed ensure."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "medium"
+  },
+  "CONTENT_NOT_FOUND": {
+    "defaultLevel": "warn",
+    "title": "Content object could not be fetched from storage",
+    "impact": "Item or list output may omit content-backed fields.",
+    "possibleCauses": [
+      "The storage object key does not exist.",
+      "Content reader credentials or bucket configuration is wrong.",
+      "The record references a stale contentKey."
+    ],
+    "remediation": [
+      "Verify contentKey and storage provider configuration.",
+      "Check contentReaders on the retrieval client.",
+      "Confirm the object exists in the configured bucket."
+    ],
+    "retryable": true,
+    "userActionRequired": true,
+    "confidence": "medium"
+  },
+  "RELATION_FETCH_FAILED": {
+    "defaultLevel": "warn",
+    "title": "Related record fetch failed",
+    "impact": "Relation-expanded fields may be empty while core entity data still returns.",
+    "possibleCauses": [
+      "Related entity id does not exist in Mongo.",
+      "Relation target collection or descriptor is misconfigured.",
+      "Mongo read timed out or returned a transient error."
+    ],
+    "remediation": [
+      "Verify relation target ids and collection bindings.",
+      "Inspect relation descriptor include configuration.",
+      "Retry if Mongo errors were transient."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/memorix-retrieval",
-  "version": "1.9.2",
+  "version": "1.11.0",
   "description": "Read-side runtime data tier for Memorix: inventory, lists, items, slices, graph, and health",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,8 @@
   "files": [
     "dist",
     "catalox-seeds",
-    "docs"
+    "docs",
+    "metadata"
   ],
   "scripts": {
     "build": "tsc",
@@ -33,7 +34,8 @@
   "dependencies": {
     "@x12i/catalox": "^5.0.0",
     "@x12i/helpers": "^1.7.0",
-    "@x12i/memorix-descriptors": "^1.5.0",
+    "@x12i/logxer": "^4.5.0",
+    "@x12i/memorix-descriptors": "^1.6.0",
     "@x12i/xronox": "^3.9.0"
   },
   "devDependencies": {