@x12i/memorix-metadata 3.2.0 → 3.2.3

package/examples/knowx/normalized/pack.json

@@ -174,7 +174,7 @@
       "abstractTypes": [
         "Content"
       ],
-      "notes": "Ingested documents (raw/snapshots) plus free-floating KnowX knowledge items (knowx NODE/EDGE with own recordId). Entity NODE facets stay on people/work-items.",
+      "notes": "Ingested documents (raw/snapshots) plus free-floating KnowX knowledge items (knowx NODE/EDGE with own recordId). Nexum apply-plan records use nexum-* object types. Entity NODE facets stay on people/work-items.",
       "contentTypes": [
         {
           "id": "raw",
@@ -191,6 +191,11 @@
           "id": "knowx",
           "notes": "Knowledge item payloads — data.kind NODE|EDGE (topology); data.identity.category claim|fact|opinion|assumption (AI classifier, orthogonal to kind); data.epistemic.state is review standing (≠ identity.category); provenance mandatory. EDGE and content-derived items use their own recordId."
         },
+        {
+          "id": "nexum",
+          "required": false,
+          "notes": "Optional Nexum snapshot facet; durable apply-plan kinds use nexum-* object types"
+        },
         {
           "id": "workflow",
           "notes": "Human review assignment sibling for knowledge items"
@@ -1119,10 +1124,103 @@
         "notes": "Worker fallback when AI_SKILLS_URL unset / compile cannot resolve skill origin. KNOWX_EXTRACT_WORKER_URL honored only when KNOWX_AI_SIM=1 (test-only)."
       }
     },
+    {
+      "id": "knowx-retrieval-index",
+      "name": "Index / candidates (candidate-retrieval)",
+      "description": "Companion step for @x12i/candidate-retrival-service (MEMORIX_RETRIEVAL_URL, default local :6560). (1) POST /v1/candidates for open knowx drafts so associate sees corpus-scale priors, (2) POST /v1/index/upsert for knowx drafts (knowx.knowledge) and Content snapshots (knowx.snapshot). Soft-skips only when URL unset; when URL is set, remote failures hard-fail the step — associate then receives real CRS priors.",
+      "role": "agent",
+      "capabilities": [
+        "analyze"
+      ],
+      "memorixAccess": [],
+      "inputs": [
+        {
+          "id": "knowxDrafts",
+          "abstractType": "Content",
+          "description": "Drafts from knowx-extract / write path (candidates + upsert)"
+        },
+        {
+          "id": "contentDrafts",
+          "abstractType": "Content",
+          "description": "Optional Content snapshot drafts from knowx-promote-content (knowx.snapshot upsert)"
+        },
+        {
+          "id": "fetchCandidates",
+          "control": true,
+          "description": "When false, index only (no /v1/candidates). Default true when knowxDrafts present."
+        }
+      ],
+      "outputs": [
+        {
+          "id": "existingKnowx",
+          "abstractType": "Content",
+          "description": "Ranked prior knowx from /v1/candidates for associate (self-ids excluded)"
+        },
+        {
+          "id": "retrieval",
+          "control": true,
+          "description": "enabled / upserted / warnings for ops"
+        },
+        {
+          "id": "indexedRecordIds",
+          "control": true,
+          "description": "recordId / contentId list submitted for upsert"
+        }
+      ],
+      "invocation": {
+        "kind": "worker",
+        "operation": "knowx-retrieval-index",
+        "notes": "Requires MEMORIX_RETRIEVAL_URL (or CANDIDATE_RETRIEVAL_URL) pointing at the candidate-retrieval companion."
+      }
+    },
+    {
+      "id": "knowx-nexum",
+      "name": "Knowledge graph analyze (Nexum)",
+      "description": "KnowX control-plane adapter for @x12i/nexum (MEMORIX_NEXUM_URL, default local :7500). Maps KnowX pipeline bags (extract/promote/write) to Nexum items[], POSTs memorix-capability/1 analyze (serviceId nexum), returns proposedGraph. Soft-skips only when URL unset; when URL is set (or MEMORIX_NEXUM_REQUIRED=1), companion failures hard-fail. Persistence is platform write-record mode nexum after this step. Explore view: createKnowxNexumExploreClient (NEXUM_API_URL · :8080).",
+      "role": "agent",
+      "capabilities": [
+        "analyze"
+      ],
+      "memorixAccess": [],
+      "inputs": [
+        {
+          "id": "knowxDrafts",
+          "abstractType": "Content",
+          "description": "Drafts from knowx-extract / write path (structured items for Nexum)"
+        },
+        {
+          "id": "contentDrafts",
+          "abstractType": "Content",
+          "description": "Optional Content snapshot drafts from knowx-promote-content"
+        }
+      ],
+      "outputs": [
+        {
+          "id": "apply-plan",
+          "control": true,
+          "description": "x12i-nexum/1 replace-contribution / remove-contribution apply plan (not applied by this step)"
+        },
+        {
+          "id": "nexum",
+          "control": true,
+          "description": "enabled / itemCount / warnings for ops"
+        },
+        {
+          "id": "diagnostics",
+          "control": true,
+          "description": "Remote worker diagnostics"
+        }
+      ],
+      "invocation": {
+        "kind": "worker",
+        "operation": "analyze",
+        "notes": "KnowX control-plane adapter (serviceId knowx-nexum — not nexum). Maps bags then POSTs to nexum-worker via MEMORIX_NEXUM_URL (alias NEXUM_URL). Compile must not treat this id as serviceId nexum. Explore REST uses MEMORIX_NEXUM_READ_URL + createKnowxNexumExploreClient."
+      }
+    },
     {
       "id": "knowx-associate-knowledge",
       "name": "Associate knowledge",
-      "description": "Classify extracted drafts against existing Content scope: known, novel, contradicts. When aiService is bound, Memorix invokes Catalox skill knowx.associate-knowledge and pushes existingKnowx from Explore. Worker fallback fetches via memorix callback or accepts pushed existingKnowx. Returns classification buckets + candidate knowledge relationship plans. Does not persist.",
+      "description": "Classify extracted drafts against existing Content scope: known, novel, contradicts. Prefer existingKnowx from knowx-retrieval-index (/v1/candidates). When aiService is bound, Memorix invokes Catalox skill knowx.associate-knowledge and may also push explore/catalog. Worker fallback uses pushed existingKnowx or Explore list. Returns classification buckets + candidate knowledge relationship plans. Does not persist.",
       "role": "agent",
       "capabilities": [
         "analyze"
@@ -1139,7 +1237,7 @@
         {
           "id": "existingKnowx",
           "abstractType": "Content",
-          "description": "Optional pushed existing Content for offline/fixture runs"
+          "description": "Optional: pipeline output from knowx-retrieval-index, fixtures, or Explore push"
         }
       ],
       "outputs": [
@@ -1215,7 +1313,7 @@
       "id": "knowx-ingest-associate",
       "name": "Ingest then associate knowledge and entities",
       "trigger": "explicit",
-      "description": "extract → write knowx → associate-knowledge → relationship-write → associate-entities → relationship-write. Services do not persist; write-record and relationship-write do.",
+      "description": "extract → write knowx → retrieval-index (candidate-retrieval upsert + candidates) → nexum (proposedGraph) → write-graph (mode nexum persist) → associate-knowledge → relationship-write → associate-entities → relationship-write. Services do not persist; write-record and relationship-write do.",
       "steps": [
         {
           "id": "extract",
@@ -1236,17 +1334,78 @@
             }
           ]
         },
+        {
+          "id": "index-knowx",
+          "kind": "analyze",
+          "serviceId": "knowx-retrieval-index",
+          "dependsOn": [
+            "write-knowx"
+          ],
+          "inputs": [
+            {
+              "fromStep": "extract",
+              "key": "extract"
+            },
+            {
+              "fromStep": "write-knowx",
+              "key": "write-knowx"
+            }
+          ],
+          "notes": "POST /v1/candidates for associate + /v1/index/upsert (knowx.knowledge). Soft-skip only when MEMORIX_RETRIEVAL_URL unset; when set, remote failures hard-fail."
+        },
+        {
+          "id": "nexum",
+          "kind": "analyze",
+          "serviceId": "knowx-nexum",
+          "dependsOn": [
+            "index-knowx"
+          ],
+          "inputs": [
+            {
+              "fromStep": "extract",
+              "key": "extract"
+            },
+            {
+              "fromStep": "write-knowx",
+              "key": "write-knowx"
+            }
+          ],
+          "notes": "KnowX mapper POSTs Nexum analyze (proposedGraph). Soft-skip only when MEMORIX_NEXUM_URL unset; when set, remote failures hard-fail. Platform write-record mode nexum persists proposedGraph."
+        },
+        {
+          "id": "write-graph",
+          "kind": "write-record",
+          "contentType": "snapshots",
+          "portConfig": {
+            "mode": "nexum"
+          },
+          "dependsOn": [
+            "nexum"
+          ],
+          "inputs": [
+            {
+              "fromStep": "nexum",
+              "key": "nexum"
+            }
+          ],
+          "notes": "mode nexum — create-or-update proposedGraph as content/snapshots. Empty plan when companion soft-skips is a no-op success."
+        },
         {
           "id": "associate-knowledge",
           "kind": "analyze",
           "serviceId": "knowx-associate-knowledge",
           "dependsOn": [
-            "write-knowx"
+            "index-knowx",
+            "write-graph"
           ],
           "inputs": [
             {
               "fromStep": "extract",
               "key": "extract"
+            },
+            {
+              "fromStep": "index-knowx",
+              "key": "index-knowx"
             }
           ]
         },
@@ -1298,7 +1457,7 @@
       "id": "knowx-ingest-content-source",
       "name": "Folder connector ingest then derive knowledge",
       "trigger": "explicit",
-      "description": "knowx-folder-pull (exact raw via CF collectStream) → knowx-promote-content (format→Markdown snapshots) → knowx-extract → write knowx → associate-knowledge → relationship-write → associate-entities → relationship-write.",
+      "description": "knowx-folder-pull → promote-content → index-snapshots (CRS knowx.snapshot) → extract → write knowx → index-knowx (CRS candidates + knowx.knowledge) → nexum (proposedGraph) → write-graph (mode nexum) → associate-knowledge → relationship-write → associate-entities → relationship-write.",
       "steps": [
         {
           "id": "folder-pull",
@@ -1319,12 +1478,27 @@
             }
           ]
         },
+        {
+          "id": "index-snapshots",
+          "kind": "analyze",
+          "serviceId": "knowx-retrieval-index",
+          "dependsOn": [
+            "promote-content"
+          ],
+          "inputs": [
+            {
+              "fromStep": "promote-content",
+              "key": "promote-content"
+            }
+          ],
+          "notes": "Index Content snapshots only (knowx.snapshot; no knowxDrafts → no candidates). Soft-skip when CRS unset/down."
+        },
         {
           "id": "extract",
           "kind": "analyze",
           "serviceId": "knowx-extract",
           "dependsOn": [
-            "promote-content"
+            "index-snapshots"
           ],
           "inputs": [
             {
@@ -1347,12 +1521,77 @@
             }
           ]
         },
+        {
+          "id": "index-knowx",
+          "kind": "analyze",
+          "serviceId": "knowx-retrieval-index",
+          "dependsOn": [
+            "write-knowx"
+          ],
+          "inputs": [
+            {
+              "fromStep": "extract",
+              "key": "extract"
+            },
+            {
+              "fromStep": "write-knowx",
+              "key": "write-knowx"
+            },
+            {
+              "fromStep": "promote-content",
+              "key": "promote-content"
+            }
+          ],
+          "notes": "POST /v1/candidates for associate + upsert knowx + re-touch snapshots."
+        },
+        {
+          "id": "nexum",
+          "kind": "analyze",
+          "serviceId": "knowx-nexum",
+          "dependsOn": [
+            "index-knowx"
+          ],
+          "inputs": [
+            {
+              "fromStep": "extract",
+              "key": "extract"
+            },
+            {
+              "fromStep": "write-knowx",
+              "key": "write-knowx"
+            },
+            {
+              "fromStep": "promote-content",
+              "key": "promote-content"
+            }
+          ],
+          "notes": "KnowX mapper POSTs Nexum analyze from promote + extract bags. Soft-skip when MEMORIX_NEXUM_URL unset; when set, remote failures hard-fail. write-graph persists proposedGraph."
+        },
+        {
+          "id": "write-graph",
+          "kind": "write-record",
+          "contentType": "snapshots",
+          "portConfig": {
+            "mode": "nexum"
+          },
+          "dependsOn": [
+            "nexum"
+          ],
+          "inputs": [
+            {
+              "fromStep": "nexum",
+              "key": "nexum"
+            }
+          ],
+          "notes": "mode nexum — create-or-update proposedGraph as content/snapshots."
+        },
         {
           "id": "associate-knowledge",
           "kind": "analyze",
           "serviceId": "knowx-associate-knowledge",
           "dependsOn": [
-            "write-knowx"
+            "index-knowx",
+            "write-graph"
           ],
           "inputs": [
             {
@@ -1362,6 +1601,10 @@
             {
               "fromStep": "write-knowx",
               "key": "write-knowx"
+            },
+            {
+              "fromStep": "index-knowx",
+              "key": "index-knowx"
             }
           ]
         },
@@ -1417,7 +1660,7 @@
       "id": "knowx-ingest-managed-item",
       "name": "Managed Drive item ingest then derive knowledge",
       "trigger": "explicit",
-      "description": "knowx-managed-pull (exact raw via CF collectStream) → knowx-promote-content → knowx-extract → write knowx → associate-knowledge → relationship-write → associate-entities → relationship-write.",
+      "description": "knowx-managed-pull → promote-content → index-snapshots (CRS) → extract → write knowx → index-knowx (CRS candidates + upsert) → nexum (proposedGraph) → write-graph (mode nexum) → associate-knowledge → relationship-write → associate-entities → relationship-write.",
       "steps": [
         {
           "id": "managed-pull",
@@ -1438,12 +1681,27 @@
             }
           ]
         },
+        {
+          "id": "index-snapshots",
+          "kind": "analyze",
+          "serviceId": "knowx-retrieval-index",
+          "dependsOn": [
+            "promote-content"
+          ],
+          "inputs": [
+            {
+              "fromStep": "promote-content",
+              "key": "promote-content"
+            }
+          ],
+          "notes": "Index Content snapshots only (knowx.snapshot; no knowxDrafts → no candidates). Soft-skip when CRS unset/down."
+        },
         {
           "id": "extract",
           "kind": "analyze",
           "serviceId": "knowx-extract",
           "dependsOn": [
-            "promote-content"
+            "index-snapshots"
           ],
           "inputs": [
             {
@@ -1466,12 +1724,77 @@
             }
           ]
         },
+        {
+          "id": "index-knowx",
+          "kind": "analyze",
+          "serviceId": "knowx-retrieval-index",
+          "dependsOn": [
+            "write-knowx"
+          ],
+          "inputs": [
+            {
+              "fromStep": "extract",
+              "key": "extract"
+            },
+            {
+              "fromStep": "write-knowx",
+              "key": "write-knowx"
+            },
+            {
+              "fromStep": "promote-content",
+              "key": "promote-content"
+            }
+          ],
+          "notes": "POST /v1/candidates for associate + upsert knowx + re-touch snapshots."
+        },
+        {
+          "id": "nexum",
+          "kind": "analyze",
+          "serviceId": "knowx-nexum",
+          "dependsOn": [
+            "index-knowx"
+          ],
+          "inputs": [
+            {
+              "fromStep": "extract",
+              "key": "extract"
+            },
+            {
+              "fromStep": "write-knowx",
+              "key": "write-knowx"
+            },
+            {
+              "fromStep": "promote-content",
+              "key": "promote-content"
+            }
+          ],
+          "notes": "KnowX mapper POSTs Nexum analyze from promote + extract bags. Soft-skip when MEMORIX_NEXUM_URL unset; when set, remote failures hard-fail. write-graph persists proposedGraph."
+        },
+        {
+          "id": "write-graph",
+          "kind": "write-record",
+          "contentType": "snapshots",
+          "portConfig": {
+            "mode": "nexum"
+          },
+          "dependsOn": [
+            "nexum"
+          ],
+          "inputs": [
+            {
+              "fromStep": "nexum",
+              "key": "nexum"
+            }
+          ],
+          "notes": "mode nexum — create-or-update proposedGraph as content/snapshots."
+        },
         {
           "id": "associate-knowledge",
           "kind": "analyze",
           "serviceId": "knowx-associate-knowledge",
           "dependsOn": [
-            "write-knowx"
+            "index-knowx",
+            "write-graph"
           ],
           "inputs": [
             {
@@ -1481,6 +1804,10 @@
             {
               "fromStep": "write-knowx",
               "key": "write-knowx"
+            },
+            {
+              "fromStep": "index-knowx",
+              "key": "index-knowx"
             }
           ]
         },