@x12i/memorix-service 3.2.1 → 3.3.0

package/openapi/openapi.json

@@ -44,7 +44,19 @@
     },
     {
       "name": "Jobs",
-      "description": "Jobs Manager repeated-work API. P3 reads and P4 writes live. See .operational/jobs-v1-api-FR.md"
+      "description": "Jobs Manager repeated-work API. P3 reads and P4 writes live."
+    },
+    {
+      "name": "Connectors",
+      "description": "Unified connector catalog (registry + builtins + MGC remote hosts)"
+    },
+    {
+      "name": "Catalog",
+      "description": "Global product package catalog (Memorix typed store)"
+    },
+    {
+      "name": "ConnectorOps",
+      "description": "MCO-01/MCO-02 org-scoped connector-op overrides and attempt stats ledger. Path orgId must match x-memorix-org-id."
     }
   ],
   "paths": {
@@ -9581,161 +9593,1533 @@
         },
         "description": "Catalog for Jobs Manager execution-target picker."
       }
-    }
-  },
-  "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"
+    "/api/connectors": {
+      "get": {
+        "operationId": "listConnectors",
+        "summary": "List unified connectors (registry + builtins + MGC live catalogs)",
+        "tags": [
+          "Connectors"
         ],
-        "additionalProperties": false,
-        "properties": {
-          "orgId": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Data universe / org isolation key"
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
           },
-          "agentIds": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "minLength": 1
-            },
-            "minItems": 1,
-            "uniqueItems": true,
-            "description": "Effective metadata agent chain (canonicalized/sorted)"
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
           }
-        },
-        "example": {
-          "orgId": "acme",
-          "agentIds": [
-            "opx",
-            "fieldstone"
-          ]
-        }
-      },
-      "MemorixIdentifier": {
-        "type": "object",
-        "required": [
-          "kind",
-          "value"
         ],
-        "properties": {
-          "kind": {
-            "type": "string"
-          },
-          "value": {
-            "type": "string"
-          },
-          "issuer": {
-            "type": "string"
+        "responses": {
+          "200": {
+            "description": "Merged connector catalog. Live MGC rows only appear when the host is reachable and has them installed (partial pack seed is normal).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "scope",
+                    "sourceConnectors",
+                    "targetConnectors",
+                    "connectors",
+                    "genericConnectors"
+                  ],
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "sourceConnectors": {
+                      "type": "array",
+                      "description": "Pull-capable rows (isSource)",
+                      "items": {
+                        "$ref": "#/components/schemas/ConnectorCatalogEntry"
+                      }
+                    },
+                    "targetConnectors": {
+                      "type": "array",
+                      "description": "Deliver-capable rows (isTarget)",
+                      "items": {
+                        "$ref": "#/components/schemas/ConnectorCatalogEntry"
+                      }
+                    },
+                    "connectors": {
+                      "type": "array",
+                      "description": "Compat alias of sourceConnectors",
+                      "items": {
+                        "$ref": "#/components/schemas/ConnectorCatalogEntry"
+                      }
+                    },
+                    "genericConnectors": {
+                      "type": "object",
+                      "properties": {
+                        "sourceServiceUrl": {
+                          "type": "string",
+                          "nullable": true,
+                          "description": "Configured MGC_SOURCE_SERVICE_URL (null when unset)"
+                        },
+                        "targetServiceUrl": {
+                          "type": "string",
+                          "nullable": true,
+                          "description": "Configured MGC_TARGET_SERVICE_URL (null when unset)"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
           },
-          "normalizedValue": {
-            "type": "string"
+          "400": {
+            "description": "Bad request / validation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
           }
-        }
-      },
-      "MemorixRecordV2": {
-        "type": "object",
-        "required": [
-          "format",
-          "recordId",
-          "revision",
-          "objectType",
-          "contentType",
-          "dataCategory",
-          "concept",
-          "data",
-          "_system"
+        },
+        "description": "Merges connector registry, platform builtins (opx/knowx), and live generic-connector host catalogs. Prefers explicit role from the host; forwards usageModel (stream|service), classification, tags, purpose, and definitionHash when present. Never invents MGC package ids when a host is down or seed sets omit them."
+      }
+    },
+    "/api/catalog": {
+      "get": {
+        "operationId": "catalogListComponents",
+        "summary": "List global catalog components (Magit store or flat + local kinds)",
+        "tags": [
+          "Catalog"
         ],
-        "properties": {
-          "format": {
-            "type": "string",
-            "enum": [
-              "memorix-record/2"
-            ]
-          },
-          "recordId": {
-            "type": "string"
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
           },
-          "revision": {
-            "type": "integer",
-            "minimum": 1
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
           },
-          "objectType": {
-            "type": "string"
+          {
+            "name": "kind",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "agent",
+                "connector",
+                "service",
+                "pipeline",
+                "runtime-service",
+                "all"
+              ]
+            }
           },
-          "contentType": {
-            "type": "string"
+          {
+            "name": "publisher",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
           },
-          "dataCategory": {
-            "type": "string",
-            "enum": [
-              "entity",
-              "event",
-              "knowledge"
-            ]
+          {
+            "name": "q",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
           },
-          "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"
+          {
+            "name": "include",
+            "in": "query",
+            "description": "Comma-separated: releases,deployments",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Catalog component list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "packageTypeId": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "typedStoreConfigured": {
+                      "type": "boolean"
+                    },
+                    "components": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    },
+                    "note": {
+                      "type": "string"
                     }
                   }
                 }
               }
             }
           },
-          "data": {
-            "type": "object",
-            "additionalProperties": true
-          },
-          "analytics": {
+          "503": {
+            "description": "Magit unavailable"
+          }
+        }
+      }
+    },
+    "/api/catalog/{kind}/{id}": {
+      "get": {
+        "operationId": "catalogGetComponent",
+        "summary": "Get one catalog component",
+        "tags": [
+          "Catalog"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "kind",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "include",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "publisher",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Component detail"
+          },
+          "404": {
+            "description": "Not found"
+          }
+        }
+      }
+    },
+    "/api/catalog/{kind}/{id}/releases": {
+      "get": {
+        "operationId": "catalogListReleases",
+        "summary": "List Magit package releases for a component",
+        "tags": [
+          "Catalog"
+        ],
+        "parameters": [
+          {
+            "name": "kind",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "publisher",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "maxCount",
+            "in": "query",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Release list"
+          }
+        }
+      }
+    },
+    "/api/metadata/packages": {
+      "get": {
+        "operationId": "metadataListPackages",
+        "summary": "List packable identities and/or Magit catalog (source=)",
+        "tags": [
+          "Metadata"
+        ],
+        "parameters": [
+          {
+            "name": "kind",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "source",
+            "in": "query",
+            "description": "packable (default) | catalog | all",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "packable",
+                "catalog",
+                "all"
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Package identities"
+          },
+          "503": {
+            "description": "Magit unavailable"
+          }
+        }
+      }
+    },
+    "/api/metadata/packages/pack": {
+      "post": {
+        "operationId": "metadataPackPackage",
+        "summary": "Pack installed metadata into Magit package catalog",
+        "tags": [
+          "Metadata"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "kind",
+                  "id",
+                  "message"
+                ],
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "enum": [
+                      "agent",
+                      "connector",
+                      "service"
+                    ]
+                  },
+                  "id": {
+                    "type": "string"
+                  },
+                  "message": {
+                    "type": "string"
+                  },
+                  "mode": {
+                    "type": "string",
+                    "enum": [
+                      "narrow",
+                      "full"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Packed version",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "packed": {
+                      "type": "boolean"
+                    },
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "agent",
+                        "connector",
+                        "service"
+                      ]
+                    },
+                    "id": {
+                      "type": "string"
+                    },
+                    "agentId": {
+                      "type": "string"
+                    },
+                    "version": {
+                      "type": "string"
+                    },
+                    "checksum": {
+                      "type": "string"
+                    },
+                    "reused": {
+                      "type": "boolean"
+                    },
+                    "published": {
+                      "type": "boolean",
+                      "description": "True when Magit typed-store pack was remotely published. Absent on flat catalog packs."
+                    },
+                    "storeId": {
+                      "type": "string",
+                      "description": "Typed-store id on Mode A packs. Sensitive recovery material — not for bulk inventory."
+                    },
+                    "packageTypeId": {
+                      "type": "string",
+                      "description": "Structure language id for the typed store (safe)."
+                    },
+                    "note": {
+                      "type": "string"
+                    },
+                    "mode": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "enum": [
+                        "narrow",
+                        "full",
+                        null
+                      ]
+                    },
+                    "bundled": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "kind": {
+                            "type": "string"
+                          },
+                          "id": {
+                            "type": "string"
+                          },
+                          "version": {
+                            "type": "string"
+                          },
+                          "commit": {
+                            "type": "string"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/metadata/packages/restore": {
+      "post": {
+        "operationId": "metadataRestorePackage",
+        "summary": "Fetch Magit package and install into org",
+        "tags": [
+          "Metadata"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Restore result"
+          }
+        }
+      }
+    },
+    "/api/connector-ops/v1/orgs/{orgId}/connectors/{connectorId}/ops/{opId}/override": {
+      "put": {
+        "operationId": "connectorOpsPutOverride",
+        "summary": "Set org-scoped connector-op override (MCO-01)",
+        "tags": [
+          "ConnectorOps"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "name": "orgId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Organization id (must match x-memorix-org-id header)"
+          },
+          {
+            "name": "connectorId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          {
+            "name": "opId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/McoSetOpOverride"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Upserted override",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/McoOpOverride"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation / scope invalid / payload rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Path orgId mismatches header scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Durable store required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "connectorOpsGetOverride",
+        "summary": "Get one override (404 when absent/expired)",
+        "tags": [
+          "ConnectorOps"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "name": "orgId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Organization id (must match x-memorix-org-id header)"
+          },
+          {
+            "name": "connectorId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          {
+            "name": "opId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Override",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/McoOpOverride"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation / scope invalid / payload rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Path orgId mismatches header scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Durable store required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "connectorOpsClearOverride",
+        "summary": "Clear override (re-enable op)",
+        "tags": [
+          "ConnectorOps"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "name": "orgId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Organization id (must match x-memorix-org-id header)"
+          },
+          {
+            "name": "connectorId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          {
+            "name": "opId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Cleared"
+          },
+          "400": {
+            "description": "Validation / scope invalid / payload rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Path orgId mismatches header scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Durable store required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/connector-ops/v1/orgs/{orgId}/connectors/{connectorId}/overrides": {
+      "get": {
+        "operationId": "connectorOpsListOverrides",
+        "summary": "List active overrides for a connector",
+        "tags": [
+          "ConnectorOps"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "name": "orgId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Organization id (must match x-memorix-org-id header)"
+          },
+          {
+            "name": "connectorId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Override list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "orgId": {
+                      "type": "string"
+                    },
+                    "connectorId": {
+                      "type": "string"
+                    },
+                    "overrides": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/McoOpOverride"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation / scope invalid / payload rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Path orgId mismatches header scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Durable store required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/connector-ops/v1/orgs/{orgId}/connectors/{connectorId}/ops/{opId}/attempts": {
+      "post": {
+        "operationId": "connectorOpsRecordAttempt",
+        "summary": "Record one op attempt (MCO-02)",
+        "tags": [
+          "ConnectorOps"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "name": "orgId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Organization id (must match x-memorix-org-id header)"
+          },
+          {
+            "name": "connectorId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          {
+            "name": "opId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/McoOpAttemptInput"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Recorded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/McoOpAttempt"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation / scope invalid / payload rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Path orgId mismatches header scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Durable store required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "connectorOpsListAttempts",
+        "summary": "List recent attempts for an op",
+        "tags": [
+          "ConnectorOps"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "name": "orgId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Organization id (must match x-memorix-org-id header)"
+          },
+          {
+            "name": "connectorId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          {
+            "name": "opId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 200,
+              "default": 50
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Attempts",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "orgId": {
+                      "type": "string"
+                    },
+                    "connectorId": {
+                      "type": "string"
+                    },
+                    "opId": {
+                      "type": "string"
+                    },
+                    "limit": {
+                      "type": "integer"
+                    },
+                    "attempts": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/McoOpAttempt"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation / scope invalid / payload rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Path orgId mismatches header scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Durable store required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/connector-ops/v1/orgs/{orgId}/connectors/{connectorId}/ops/{opId}/stats": {
+      "get": {
+        "operationId": "connectorOpsGetStats",
+        "summary": "Get aggregate stats for one op",
+        "tags": [
+          "ConnectorOps"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "name": "orgId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Organization id (must match x-memorix-org-id header)"
+          },
+          {
+            "name": "connectorId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          {
+            "name": "opId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Stats",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/McoOpStats"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation / scope invalid / payload rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Path orgId mismatches header scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Durable store required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/connector-ops/v1/orgs/{orgId}/connectors/{connectorId}/stats": {
+      "get": {
+        "operationId": "connectorOpsListStats",
+        "summary": "List stats for all ops of a connector",
+        "tags": [
+          "ConnectorOps"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "name": "orgId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Organization id (must match x-memorix-org-id header)"
+          },
+          {
+            "name": "connectorId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Stats list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "orgId": {
+                      "type": "string"
+                    },
+                    "connectorId": {
+                      "type": "string"
+                    },
+                    "stats": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/McoOpStats"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation / scope invalid / payload rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Path orgId mismatches header scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Durable store required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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"
+          ]
+        }
+      },
+      "ConnectorCatalogEntry": {
+        "type": "object",
+        "required": [
+          "id",
+          "version",
+          "protocol",
+          "enabled",
+          "framework",
+          "displayName",
+          "capabilities",
+          "isSource",
+          "isTarget",
+          "origin"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Connector package id (connectorRef)"
+          },
+          "version": {
+            "type": "string"
+          },
+          "protocol": {
+            "type": "string",
+            "example": "memorix-connector/1"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "framework": {
+            "type": "boolean"
+          },
+          "displayName": {
+            "type": "string"
+          },
+          "capabilities": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "connectorRole": {
+            "type": "string",
+            "enum": [
+              "source",
+              "target",
+              "both"
+            ],
+            "nullable": true,
+            "description": "Authoritative direction when set (prefer over id suffix)."
+          },
+          "isSource": {
+            "type": "boolean"
+          },
+          "isTarget": {
+            "type": "boolean"
+          },
+          "origin": {
+            "type": "string",
+            "enum": [
+              "registry",
+              "builtin",
+              "generic-connectors"
+            ]
+          },
+          "hostBaseUrl": {
+            "type": "string",
+            "description": "MGC host base when origin is generic-connectors"
+          },
+          "remoteHosting": {
+            "type": "boolean"
+          },
+          "unavailableReason": {
+            "type": "string",
+            "description": "Set when the row is listed but not usable (e.g. host URL unset for stubs)"
+          },
+          "definitionHash": {
+            "type": "string",
+            "description": "Pinned hash from host catalog when available"
+          },
+          "description": {
+            "type": "string"
+          },
+          "purpose": {
+            "type": "string"
+          },
+          "classification": {
+            "type": "string",
+            "description": "Domain classification from pack catalog (e.g. cybersecurity)"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "usageModel": {
+            "type": "string",
+            "enum": [
+              "stream",
+              "service"
+            ],
+            "description": "stream = continuous sync; service = on-demand enrichment. Protocol role remains source|target only."
+          }
+        }
+      },
+      "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
           },
@@ -11439,6 +12823,201 @@
             "additionalProperties": true
           }
         }
+      },
+      "McoSetOpOverride": {
+        "type": "object",
+        "required": [
+          "enabled"
+        ],
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Required non-empty when enabled is false"
+          },
+          "updatedBy": {
+            "type": "string"
+          },
+          "expiresAt": {
+            "type": "string",
+            "nullable": true,
+            "format": "date-time"
+          }
+        }
+      },
+      "McoOpOverride": {
+        "type": "object",
+        "required": [
+          "orgId",
+          "connectorId",
+          "opId",
+          "enabled",
+          "reason",
+          "updatedAt"
+        ],
+        "properties": {
+          "orgId": {
+            "type": "string"
+          },
+          "connectorId": {
+            "type": "string"
+          },
+          "opId": {
+            "type": "string"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "reason": {
+            "type": "string"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updatedBy": {
+            "type": "string"
+          },
+          "expiresAt": {
+            "type": "string",
+            "nullable": true,
+            "format": "date-time"
+          }
+        }
+      },
+      "McoOpAttemptInput": {
+        "type": "object",
+        "required": [
+          "at",
+          "status"
+        ],
+        "properties": {
+          "at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "fail",
+              "skip",
+              "disabled"
+            ]
+          },
+          "httpStatus": {
+            "type": "integer"
+          },
+          "error": {
+            "type": "string"
+          },
+          "durationMs": {
+            "type": "number"
+          },
+          "runId": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          }
+        }
+      },
+      "McoOpAttempt": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/McoOpAttemptInput"
+          },
+          {
+            "type": "object",
+            "required": [
+              "orgId",
+              "connectorId",
+              "opId",
+              "attemptId"
+            ],
+            "properties": {
+              "orgId": {
+                "type": "string"
+              },
+              "connectorId": {
+                "type": "string"
+              },
+              "opId": {
+                "type": "string"
+              },
+              "attemptId": {
+                "type": "string"
+              }
+            }
+          }
+        ]
+      },
+      "McoOpStats": {
+        "type": "object",
+        "required": [
+          "orgId",
+          "connectorId",
+          "opId",
+          "attemptCount",
+          "okCount",
+          "failCount",
+          "skipCount",
+          "disabledCount"
+        ],
+        "properties": {
+          "orgId": {
+            "type": "string"
+          },
+          "connectorId": {
+            "type": "string"
+          },
+          "opId": {
+            "type": "string"
+          },
+          "attemptCount": {
+            "type": "integer"
+          },
+          "okCount": {
+            "type": "integer"
+          },
+          "failCount": {
+            "type": "integer"
+          },
+          "skipCount": {
+            "type": "integer"
+          },
+          "disabledCount": {
+            "type": "integer"
+          },
+          "lastSuccessAt": {
+            "type": "string",
+            "nullable": true,
+            "format": "date-time"
+          },
+          "lastFailAt": {
+            "type": "string",
+            "nullable": true,
+            "format": "date-time"
+          },
+          "lastAttemptAt": {
+            "type": "string",
+            "nullable": true,
+            "format": "date-time"
+          },
+          "lastStatus": {
+            "type": "string",
+            "nullable": true
+          },
+          "recent": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
       }
     }
   }