@x12i/memorix-service 3.0.3 → 3.0.4

package/dist/openapi/openapi.json

@@ -254,7 +254,7 @@
                   "scope": {
                     "orgId": "acme",
                     "agentIds": [
-                      "ops"
+                      "opx"
                     ]
                   },
                   "platform": {
@@ -538,7 +538,7 @@
                   "scope": {
                     "orgId": "acme",
                     "agentIds": [
-                      "ops"
+                      "opx"
                     ]
                   },
                   "effective": {
@@ -916,7 +916,7 @@
                 }
               },
               "example": {
-                "packId": "ops"
+                "packId": "opx"
               }
             }
           }
@@ -1046,7 +1046,7 @@
               },
               "example": {
                 "confirm": true,
-                "packId": "ops"
+                "packId": "opx"
               }
             }
           }
@@ -1401,7 +1401,7 @@
                   "scope": {
                     "orgId": "acme",
                     "agentIds": [
-                      "ops"
+                      "opx"
                     ]
                   },
                   "addressing": {
@@ -2223,7 +2223,7 @@
                   "scope": {
                     "orgId": "acme",
                     "agentIds": [
-                      "ops"
+                      "opx"
                     ]
                   },
                   "direction": "forward",
@@ -2736,7 +2736,7 @@
             }
           }
         },
-        "description": "removeDefinitionLinks — other definitions untouched"
+        "description": "removeDefinitionLinks \u2014 other definitions untouched"
       }
     },
     "/api/relationships/related-property": {
@@ -3183,17 +3183,34 @@
                       "type": "array",
                       "items": {
                         "type": "object",
+                        "required": [
+                          "id"
+                        ],
                         "properties": {
-                          "sourceId": {
+                          "id": {
                             "type": "string"
                           },
-                          "credentialRef": {
+                          "name": {
+                            "type": "string"
+                          },
+                          "kind": {
                             "type": "string"
                           },
-                          "mode": {
+                          "credentialRef": {
                             "type": "string"
+                          },
+                          "routes": {
+                            "type": "array",
+                            "items": {
+                              "$ref": "#/components/schemas/MemorySourceRoute"
+                            }
+                          },
+                          "provenance": {
+                            "type": "object",
+                            "additionalProperties": true
                           }
-                        }
+                        },
+                        "additionalProperties": true
                       }
                     },
                     "note": {
@@ -5109,7 +5126,7 @@
     "/api/intelligence/compare": {
       "post": {
         "operationId": "intelligenceCompare",
-        "summary": "Compare proposals to approved ops",
+        "summary": "Compare proposals to approved opx",
         "tags": [
           "Intelligence"
         ],
@@ -5742,222 +5759,1251 @@
           }
         }
       }
-    }
-  },
-  "components": {
-    "parameters": {
-      "XMemorixOrgId": {
-        "name": "x-memorix-org-id",
-        "in": "header",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "minLength": 1
-        },
-        "description": "Organization / data-universe id"
-      },
-      "XMemorixAgentIds": {
-        "name": "x-memorix-agent-ids",
-        "in": "header",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "minLength": 1
-        },
-        "description": "Comma-separated agentIds for effective metadata",
-        "example": "ops,fieldstone"
-      }
     },
-    "schemas": {
-      "MemorixScope": {
-        "type": "object",
-        "required": [
-          "orgId",
-          "agentIds"
-        ],
-        "additionalProperties": false,
-        "properties": {
-          "orgId": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Data universe / org isolation key"
-          },
-          "agentIds": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "minLength": 1
-            },
-            "minItems": 1,
-            "uniqueItems": true,
-            "description": "Effective metadata agent chain (canonicalized/sorted)"
-          }
-        },
-        "example": {
-          "orgId": "acme",
-          "agentIds": [
-            "ops",
-            "fieldstone"
-          ]
-        }
-      },
-      "MemorixIdentifier": {
-        "type": "object",
-        "required": [
-          "kind",
-          "value"
+    "/api/memory/sources/{sourceId}/connection": {
+      "get": {
+        "operationId": "memoryGetSourceConnection",
+        "summary": "Probe source connection (configured URL + reachability)",
+        "tags": [
+          "Memory"
         ],
-        "properties": {
-          "kind": {
-            "type": "string"
-          },
-          "value": {
-            "type": "string"
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
           },
-          "issuer": {
-            "type": "string"
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
           },
-          "normalizedValue": {
-            "type": "string"
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
           }
-        }
-      },
-      "MemorixRecordV2": {
-        "type": "object",
-        "required": [
-          "format",
-          "recordId",
-          "revision",
-          "objectType",
-          "contentType",
-          "dataCategory",
-          "concept",
-          "data",
-          "_system"
         ],
-        "properties": {
-          "format": {
-            "type": "string",
-            "enum": [
-              "memorix-record/2"
-            ]
-          },
-          "recordId": {
-            "type": "string"
-          },
-          "revision": {
-            "type": "integer",
-            "minimum": 1
-          },
-          "objectType": {
-            "type": "string"
-          },
-          "contentType": {
-            "type": "string"
-          },
-          "dataCategory": {
-            "type": "string",
-            "enum": [
-              "entity",
-              "event",
-              "knowledge"
-            ]
-          },
-          "concept": {
-            "type": "object",
-            "required": [
-              "title",
-              "identifiers"
-            ],
-            "properties": {
-              "title": {
-                "type": "string"
-              },
-              "identifiers": {
-                "type": "object",
-                "required": [
-                  "primary"
-                ],
-                "properties": {
-                  "primary": {
-                    "$ref": "#/components/schemas/MemorixIdentifier"
-                  },
-                  "alternates": {
-                    "type": "array",
-                    "items": {
-                      "$ref": "#/components/schemas/MemorixIdentifier"
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "data": {
-            "type": "object",
-            "additionalProperties": true
-          },
-          "analytics": {
-            "type": "object",
-            "additionalProperties": true
-          },
-          "enrichment": {
-            "type": "object",
-            "additionalProperties": true
-          },
-          "insights": {
-            "type": "object",
-            "additionalProperties": true
-          },
-          "_system": {
-            "type": "object",
-            "required": [
-              "state",
-              "createdAt",
-              "modifiedAt"
-            ],
-            "properties": {
-              "state": {
-                "type": "string",
-                "enum": [
-                  "active",
-                  "archived",
-                  "superseded"
-                ]
-              },
-              "createdAt": {
-                "type": "string",
-                "format": "date-time"
-              },
-              "modifiedAt": {
-                "type": "string",
-                "format": "date-time"
-              },
-              "observedAt": {
-                "type": "string",
-                "format": "date-time"
-              },
-              "lifecycle": {
-                "type": "array",
-                "items": {
+        "responses": {
+          "200": {
+            "description": "Connection probe result",
+            "content": {
+              "application/json": {
+                "schema": {
                   "type": "object",
                   "required": [
-                    "process",
-                    "processedAt"
+                    "scope",
+                    "sourceId",
+                    "status",
+                    "configured",
+                    "reachable",
+                    "checkedAt"
                   ],
                   "properties": {
-                    "process": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "sourceId": {
                       "type": "string"
                     },
-                    "processedAt": {
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "Connected",
+                        "Unreachable",
+                        "Missing URL"
+                      ]
+                    },
+                    "configured": {
+                      "type": "boolean"
+                    },
+                    "reachable": {
+                      "type": "boolean"
+                    },
+                    "checkedAt": {
                       "type": "string",
                       "format": "date-time"
                     }
                   }
                 }
-              },
-              "provenance": {
-                "type": "object",
-                "additionalProperties": true
+              }
+            }
+          },
+          "404": {
+            "description": "Source not in effective metadata",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/memory/sources/{sourceId}/checkpoints": {
+      "get": {
+        "operationId": "memoryListSourceCheckpoints",
+        "summary": "List source checkpoints",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "mode",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "knowledge",
+                "context"
+              ]
+            }
+          },
+          {
+            "name": "technical",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Checkpoint summaries for source routes",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "scope",
+                    "sourceId",
+                    "checkpoints"
+                  ],
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "sourceId": {
+                      "type": "string"
+                    },
+                    "checkpoints": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/MemoryCheckpointSummary"
+                      }
+                    },
+                    "note": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request / validation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "operationId": "memoryPutSourceCheckpoint",
+        "summary": "Set source checkpoint (called services)",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "objectType"
+                ],
+                "properties": {
+                  "objectType": {
+                    "type": "string"
+                  },
+                  "routeEndpoint": {
+                    "type": "string"
+                  },
+                  "mode": {
+                    "type": "string",
+                    "enum": [
+                      "knowledge",
+                      "context"
+                    ]
+                  },
+                  "workRef": {
+                    "type": "string"
+                  },
+                  "method": {
+                    "type": "string",
+                    "enum": [
+                      "cursor",
+                      "watermark",
+                      "fullScanHash"
+                    ]
+                  },
+                  "committedCursor": {
+                    "type": "string",
+                    "nullable": true
+                  },
+                  "watermarkValue": {
+                    "type": "string",
+                    "nullable": true
+                  },
+                  "fingerprintsEstablished": {
+                    "type": "boolean"
+                  },
+                  "pullId": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Checkpoint saved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "sourceId": {
+                      "type": "string"
+                    },
+                    "checkpoint": {
+                      "$ref": "#/components/schemas/MemoryCheckpointSummary"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request / validation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/memory/sources/{sourceId}/checkpoints/{checkpointKey}": {
+      "get": {
+        "operationId": "memoryGetSourceCheckpoint",
+        "summary": "Get one source checkpoint (includes technical cursor)",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "checkpointKey",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Checkpoint with technical details",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "sourceId": {
+                      "type": "string"
+                    },
+                    "checkpoint": {
+                      "$ref": "#/components/schemas/MemoryCheckpointSummary"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request / validation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/memory/sources/{sourceId}/checkpoints/reset": {
+      "post": {
+        "operationId": "memoryResetSourceCheckpoint",
+        "summary": "Reset source checkpoint(s)",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "objectType": {
+                    "type": "string"
+                  },
+                  "routeEndpoint": {
+                    "type": "string"
+                  },
+                  "mode": {
+                    "type": "string",
+                    "enum": [
+                      "knowledge",
+                      "context"
+                    ]
+                  },
+                  "workRef": {
+                    "type": "string"
+                  },
+                  "all": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Checkpoint(s) cleared",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "sourceId": {
+                      "type": "string"
+                    },
+                    "reset": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "note": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request / validation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/pipelines/runs/{runId}/cancel": {
+      "post": {
+        "operationId": "pipelinesCancel",
+        "summary": "Cancel pipeline run",
+        "tags": [
+          "Pipelines"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Cancelled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": {
+                      "type": "object"
+                    },
+                    "runId": {
+                      "type": "string"
+                    },
+                    "status": {
+                      "type": "string"
+                    },
+                    "run": {
+                      "type": "object"
+                    },
+                    "note": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request / validation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found"
+          },
+          "503": {
+            "description": "Service unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/pipelines/runs/{runId}/artifacts": {
+      "get": {
+        "operationId": "pipelinesListArtifacts",
+        "summary": "List pipeline run artifacts",
+        "tags": [
+          "Pipelines"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Artifact refs",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found"
+          }
+        }
+      }
+    },
+    "/api/pipelines/runs/{runId}/artifacts/{artifactId}": {
+      "get": {
+        "operationId": "pipelinesGetArtifact",
+        "summary": "Get pipeline run artifact",
+        "tags": [
+          "Pipelines"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "artifactId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Artifact payload",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found"
+          }
+        }
+      }
+    },
+    "/api/memory/sources/{sourceId}/commit-page": {
+      "post": {
+        "operationId": "memoryCommitPage",
+        "summary": "Atomically land raw page and commit checkpoint",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "objectType",
+                  "items",
+                  "expectedCheckpointRevision"
+                ],
+                "properties": {
+                  "objectType": {
+                    "type": "string"
+                  },
+                  "routeEndpoint": {
+                    "type": "string"
+                  },
+                  "mode": {
+                    "type": "string",
+                    "enum": [
+                      "knowledge",
+                      "context"
+                    ]
+                  },
+                  "workRef": {
+                    "type": "string"
+                  },
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "object"
+                    }
+                  },
+                  "nextCheckpoint": {
+                    "type": "object"
+                  },
+                  "expectedCheckpointRevision": {
+                    "type": "integer"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Landing receipt",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "403": {
+            "description": "Access denied"
+          },
+          "409": {
+            "description": "Checkpoint revision conflict"
+          }
+        }
+      }
+    },
+    "/api/memory/sources/{sourceId}/schedule": {
+      "get": {
+        "operationId": "memoryGetSchedule",
+        "summary": "Get Memory pull schedule for a source",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "mode",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "knowledge",
+                "context"
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Schedule or null"
+          }
+        }
+      },
+      "put": {
+        "operationId": "memoryPutSchedule",
+        "summary": "Create or update Memory pull schedule",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "interval"
+                ],
+                "properties": {
+                  "interval": {
+                    "type": "object",
+                    "required": [
+                      "every",
+                      "unit"
+                    ],
+                    "properties": {
+                      "every": {
+                        "type": "integer",
+                        "minimum": 1
+                      },
+                      "unit": {
+                        "type": "string",
+                        "enum": [
+                          "minutes",
+                          "hours",
+                          "days"
+                        ]
+                      }
+                    }
+                  },
+                  "firstPull": {
+                    "type": "string",
+                    "enum": [
+                      "immediate",
+                      "after-interval"
+                    ]
+                  },
+                  "status": {
+                    "type": "string",
+                    "enum": [
+                      "active",
+                      "paused"
+                    ]
+                  },
+                  "mode": {
+                    "type": "string",
+                    "enum": [
+                      "knowledge",
+                      "context"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Saved schedule"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "memoryDeleteSchedule",
+        "summary": "Remove Memory pull schedule",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "mode",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "knowledge",
+                "context"
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Removed"
+          }
+        }
+      }
+    },
+    "/api/memory/sources/{sourceId}/schedule/pause": {
+      "post": {
+        "operationId": "memoryPauseSchedule",
+        "summary": "Pause Memory pull schedule",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Paused"
+          }
+        }
+      }
+    },
+    "/api/memory/sources/{sourceId}/schedule/resume": {
+      "post": {
+        "operationId": "memoryResumeSchedule",
+        "summary": "Resume Memory pull schedule",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Resumed"
+          }
+        }
+      }
+    },
+    "/api/memory/sources/{sourceId}/schedule/run-now": {
+      "post": {
+        "operationId": "memoryRunScheduleNow",
+        "summary": "Run Memory pull schedule now",
+        "tags": [
+          "Memory"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Pull started"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "parameters": {
+      "XMemorixOrgId": {
+        "name": "x-memorix-org-id",
+        "in": "header",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": "Organization / data-universe id"
+      },
+      "XMemorixAgentIds": {
+        "name": "x-memorix-agent-ids",
+        "in": "header",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": "Comma-separated agentIds for effective metadata",
+        "example": "ops,fieldstone"
+      }
+    },
+    "schemas": {
+      "MemorixScope": {
+        "type": "object",
+        "required": [
+          "orgId",
+          "agentIds"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "orgId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Data universe / org isolation key"
+          },
+          "agentIds": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "minItems": 1,
+            "uniqueItems": true,
+            "description": "Effective metadata agent chain (canonicalized/sorted)"
+          }
+        },
+        "example": {
+          "orgId": "acme",
+          "agentIds": [
+            "opx",
+            "fieldstone"
+          ]
+        }
+      },
+      "MemorixIdentifier": {
+        "type": "object",
+        "required": [
+          "kind",
+          "value"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string"
+          },
+          "value": {
+            "type": "string"
+          },
+          "issuer": {
+            "type": "string"
+          },
+          "normalizedValue": {
+            "type": "string"
+          }
+        }
+      },
+      "MemorixRecordV2": {
+        "type": "object",
+        "required": [
+          "format",
+          "recordId",
+          "revision",
+          "objectType",
+          "contentType",
+          "dataCategory",
+          "concept",
+          "data",
+          "_system"
+        ],
+        "properties": {
+          "format": {
+            "type": "string",
+            "enum": [
+              "memorix-record/2"
+            ]
+          },
+          "recordId": {
+            "type": "string"
+          },
+          "revision": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "objectType": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": "string"
+          },
+          "dataCategory": {
+            "type": "string",
+            "enum": [
+              "entity",
+              "event",
+              "knowledge"
+            ]
+          },
+          "concept": {
+            "type": "object",
+            "required": [
+              "title",
+              "identifiers"
+            ],
+            "properties": {
+              "title": {
+                "type": "string"
+              },
+              "identifiers": {
+                "type": "object",
+                "required": [
+                  "primary"
+                ],
+                "properties": {
+                  "primary": {
+                    "$ref": "#/components/schemas/MemorixIdentifier"
+                  },
+                  "alternates": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/MemorixIdentifier"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "data": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "analytics": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "enrichment": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "insights": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "_system": {
+            "type": "object",
+            "required": [
+              "state",
+              "createdAt",
+              "modifiedAt"
+            ],
+            "properties": {
+              "state": {
+                "type": "string",
+                "enum": [
+                  "active",
+                  "archived",
+                  "superseded"
+                ]
+              },
+              "createdAt": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "modifiedAt": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "observedAt": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "lifecycle": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "process",
+                    "processedAt"
+                  ],
+                  "properties": {
+                    "process": {
+                      "type": "string"
+                    },
+                    "processedAt": {
+                      "type": "string",
+                      "format": "date-time"
+                    }
+                  }
+                }
+              },
+              "provenance": {
+                "type": "object",
+                "additionalProperties": true
               }
             }
           }
@@ -6530,7 +7576,7 @@
           },
           "credentialRef": {
             "type": "string",
-            "description": "Credential reference only — never resolved secrets"
+            "description": "Credential reference only \u2014 never resolved secrets"
           },
           "cursor": {
             "type": "string"
@@ -6613,6 +7659,151 @@
             "items": {
               "type": "string"
             }
+          },
+          "routeSummaries": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "objectType": {
+                  "type": "string"
+                },
+                "routeEndpoint": {
+                  "type": "string"
+                },
+                "items": {
+                  "type": "integer"
+                },
+                "created": {
+                  "type": "integer"
+                },
+                "updated": {
+                  "type": "integer"
+                },
+                "deduplicated": {
+                  "type": "integer"
+                },
+                "quarantined": {
+                  "type": "integer"
+                },
+                "startingCursor": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "endingCursor": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "MemorySourceRoute": {
+        "type": "object",
+        "required": [
+          "endpoint",
+          "objectType",
+          "dataCategory"
+        ],
+        "properties": {
+          "endpoint": {
+            "type": "string"
+          },
+          "objectType": {
+            "type": "string"
+          },
+          "dataCategory": {
+            "type": "string"
+          },
+          "checkpoint": {
+            "type": "object",
+            "properties": {
+              "method": {
+                "type": "string",
+                "enum": [
+                  "cursor",
+                  "watermark",
+                  "fullScanHash"
+                ]
+              },
+              "watermarkField": {
+                "type": "string"
+              }
+            }
+          },
+          "modes": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "context",
+                "knowledge"
+              ]
+            }
+          }
+        }
+      },
+      "MemoryPullSchedule": {
+        "type": "object",
+        "properties": {
+          "scheduleId": {
+            "type": "string"
+          },
+          "sourceId": {
+            "type": "string"
+          },
+          "mode": {
+            "type": "string"
+          },
+          "interval": {
+            "type": "object",
+            "properties": {
+              "every": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "unit": {
+                "type": "string",
+                "enum": [
+                  "minutes",
+                  "hours",
+                  "days"
+                ]
+              }
+            }
+          },
+          "firstPull": {
+            "type": "string",
+            "enum": [
+              "immediate",
+              "after-interval"
+            ]
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "active",
+              "paused"
+            ]
+          },
+          "nextDueAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "lastFiredAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "lastPullId": {
+            "type": "string"
+          },
+          "lastStatus": {
+            "type": "string"
           }
         }
       },
@@ -6647,7 +7838,7 @@
           },
           "message": {
             "type": "string",
-            "description": "Sanitized — no secret payloads"
+            "description": "Sanitized \u2014 no secret payloads"
           },
           "createdAt": {
             "type": "string",
@@ -6869,6 +8060,67 @@
             "type": "string"
           }
         }
+      },
+      "MemoryCheckpointSummary": {
+        "type": "object",
+        "required": [
+          "checkpointKey",
+          "sourceId",
+          "objectType",
+          "routeEndpoint",
+          "mode",
+          "method",
+          "checkpointStatus"
+        ],
+        "properties": {
+          "checkpointKey": {
+            "type": "string"
+          },
+          "sourceId": {
+            "type": "string"
+          },
+          "objectType": {
+            "type": "string"
+          },
+          "routeEndpoint": {
+            "type": "string"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "knowledge",
+              "context"
+            ]
+          },
+          "method": {
+            "type": "string",
+            "enum": [
+              "cursor",
+              "watermark",
+              "fullScanHash"
+            ]
+          },
+          "checkpointStatus": {
+            "type": "string",
+            "enum": [
+              "saved",
+              "fingerprints_saved",
+              "not_established"
+            ]
+          },
+          "lastSuccessfulPull": {
+            "type": "string",
+            "nullable": true
+          },
+          "lastPullId": {
+            "type": "string",
+            "nullable": true
+          },
+          "technical": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
       }
     }
   }