@x12i/memorix-service 3.0.5 → 3.1.0

package/openapi/openapi.json

@@ -433,6 +433,24 @@
                       "type": "object",
                       "additionalProperties": true,
                       "nullable": true
+                    },
+                    "lineage": {
+                      "type": "object",
+                      "nullable": true,
+                      "description": "Latest install ledger entry for agentId (magitCommit when METADATA_MAGIT=1)",
+                      "properties": {
+                        "checksum": {
+                          "type": "string"
+                        },
+                        "installedAt": {
+                          "type": "string",
+                          "format": "date-time"
+                        },
+                        "magitCommit": {
+                          "type": "string",
+                          "nullable": true
+                        }
+                      }
                     }
                   }
                 }
@@ -814,6 +832,83 @@
         }
       }
     },
+    "/api/metadata/topology": {
+      "get": {
+        "operationId": "metadataTopology",
+        "summary": "Projected concrete metadata topology (OT↔OT relationships, feeds, pipeline wiring)",
+        "tags": [
+          "Metadata"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Topology nodes and edges",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "scope",
+                    "ok",
+                    "nodes",
+                    "edges"
+                  ],
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "nodes": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    },
+                    "edges": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    },
+                    "issues": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    },
+                    "note": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request / validation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/metadata/validate": {
       "post": {
         "operationId": "metadataValidate",
@@ -1041,6 +1136,18 @@
                   },
                   "reinstall": {
                     "type": "boolean"
+                  },
+                  "versionMessage": {
+                    "type": "string",
+                    "description": "Optional Magit save-version message when Magit is enabled (default on with durable Mongo; METADATA_MAGIT=0 disables); defaults to \"Install {agentId}\""
+                  },
+                  "commit": {
+                    "type": "string",
+                    "description": "Install pack reconstructed from this Magit commit (requires Magit)"
+                  },
+                  "proposalId": {
+                    "type": "string",
+                    "description": "When set with commit, ledger source is proposal-install and message includes the proposal id"
                   }
                 }
               },
@@ -1053,10 +1160,178 @@
         }
       }
     },
+    "/api/metadata/proposals/{id}/stage": {
+      "post": {
+        "operationId": "metadataStageProposal",
+        "summary": "Stage an intelligence proposal as a pack version (not live)",
+        "description": "Merges the proposal draft into the agent pack, saves a Magit version (message proposal:<id>), and validates. Never installs. Requires Magit.",
+        "tags": ["Metadata"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" },
+            "description": "Proposal id"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "agentId": { "type": "string" },
+                  "proposal": {
+                    "type": "object",
+                    "description": "Optional inline proposal body when not loading from the intelligence store",
+                    "properties": {
+                      "proposalId": { "type": "string" },
+                      "metadataKind": { "type": "string" },
+                      "metadataId": { "type": "string" },
+                      "draft": {},
+                      "scope": {
+                        "type": "object",
+                        "properties": {
+                          "agentIds": {
+                            "type": "array",
+                            "items": { "type": "string" }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Staged version (installed: false)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["scope", "commit", "installed"],
+                  "properties": {
+                    "scope": { "$ref": "#/components/schemas/MemorixScope" },
+                    "proposalId": { "type": "string" },
+                    "agentId": { "type": "string" },
+                    "commit": { "type": "string" },
+                    "checksum": { "type": "string" },
+                    "pack": { "$ref": "#/components/schemas/MetadataPack" },
+                    "validation": {},
+                    "installed": { "type": "boolean", "enum": [false] },
+                    "note": { "type": "string" }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
+              }
+            }
+          },
+          "503": {
+            "description": "Magit unavailable",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/metadata/install/bundle": {
+      "post": {
+        "operationId": "metadataInstallBundle",
+        "summary": "Atomic multi-agent install from one Magit commit",
+        "description": "Installs the same commit for each agentId. On any failure, restores prior packs for agents already applied. Requires Magit.",
+        "tags": ["Metadata"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["confirm", "commit"],
+                "properties": {
+                  "confirm": { "type": "boolean", "enum": [true] },
+                  "commit": { "type": "string" },
+                  "agentIds": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "minItems": 1
+                  },
+                  "message": { "type": "string" },
+                  "release": {
+                    "type": "string",
+                    "description": "Optional named release stamp (magitRelease)"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Bundle install result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": { "$ref": "#/components/schemas/MemorixScope" },
+                    "installed": { "type": "boolean" },
+                    "rolledBack": { "type": "boolean" },
+                    "commit": { "type": "string" },
+                    "ledgerEntries": { "type": "array", "items": {} },
+                    "restoredAgentIds": {
+                      "type": "array",
+                      "items": { "type": "string" }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation / rolled back failure",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
+              }
+            }
+          },
+          "503": {
+            "description": "Magit unavailable",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/metadata/publish": {
       "post": {
         "operationId": "metadataPublish",
-        "summary": "Explicit publish (confirm required)",
+        "summary": "Publish a named pack release (Magit apply to live)",
+        "description": "Requires Magit (default on with durable Mongo; METADATA_MAGIT=0 disables). Applies commit to live metadata for one or more agents atomically and records magitRelease on the ledger. On failure, restores prior packs for already-applied agents.",
         "tags": [
           "Metadata"
         ],
@@ -1150,6 +1425,27 @@
                     "enum": [
                       true
                     ]
+                  },
+                  "release": {
+                    "type": "string"
+                  },
+                  "commit": {
+                    "type": "string"
+                  },
+                  "agentIds": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "agentId": {
+                    "type": "string"
+                  },
+                  "message": {
+                    "type": "string"
+                  },
+                  "planHash": {
+                    "type": "string"
                   }
                 }
               }
@@ -1158,6 +1454,323 @@
         }
       }
     },
+    "/api/metadata/publish/plan": {
+      "post": {
+        "operationId": "metadataPublishPlan",
+        "summary": "Read-only publish plan for a named release",
+        "tags": ["Metadata"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["release", "commit"],
+                "properties": {
+                  "release": { "type": "string" },
+                  "commit": { "type": "string" },
+                  "agentIds": { "type": "array", "items": { "type": "string" } },
+                  "agentId": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Publish plan" },
+          "503": { "description": "Magit unavailable" }
+        }
+      }
+    },
+    "/api/metadata/rollback": {
+      "post": {
+        "operationId": "metadataRollback",
+        "summary": "Restore agent pack to a prior Magit commit",
+        "tags": ["Metadata"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["confirm", "commit"],
+                "properties": {
+                  "confirm": { "type": "boolean", "enum": [true] },
+                  "commit": { "type": "string" },
+                  "agentId": { "type": "string" },
+                  "message": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Restore result" },
+          "400": { "description": "Validation / confirmation required" },
+          "503": { "description": "Magit unavailable" }
+        }
+      }
+    },
+    "/api/metadata/diff": {
+      "post": {
+        "operationId": "metadataDiff",
+        "summary": "Diff pack versions (kind/id rows)",
+        "tags": ["Metadata"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["from", "to"],
+                "properties": {
+                  "agentId": { "type": "string" },
+                  "from": { "type": "string", "description": "commit | live | HEAD" },
+                  "to": { "type": "string", "description": "commit | live | HEAD" }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Diff rows" },
+          "503": { "description": "Magit unavailable" }
+        }
+      }
+    },
+    "/api/metadata/versions/{commit}": {
+      "get": {
+        "operationId": "metadataPackAtCommit",
+        "summary": "Pack reconstructed at a Magit commit",
+        "tags": ["Metadata"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" },
+          {
+            "name": "commit",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          },
+          {
+            "name": "agentId",
+            "in": "query",
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": { "description": "Pack at commit" },
+          "503": { "description": "Magit unavailable" }
+        }
+      }
+    },
+    "/api/metadata/versions": {
+      "post": {
+        "operationId": "metadataSaveVersion",
+        "summary": "Save a pack version (not live; Magit-backed when METADATA_MAGIT=1)",
+        "description": "Records a pack snapshot for history. Does not install. Requires METADATA_MAGIT=1 and a durable Mongo connection.",
+        "tags": [
+          "Metadata"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "message"
+                ],
+                "properties": {
+                  "message": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "pack": {
+                    "$ref": "#/components/schemas/MetadataPack"
+                  },
+                  "packId": {
+                    "type": "string"
+                  }
+                }
+              },
+              "example": {
+                "packId": "opx",
+                "message": "catalog draft before install"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Version saved (not installed)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "scope",
+                    "saved",
+                    "commit",
+                    "checksum"
+                  ],
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "saved": {
+                      "type": "boolean"
+                    },
+                    "commit": {
+                      "type": "string"
+                    },
+                    "checksum": {
+                      "type": "string"
+                    },
+                    "reused": {
+                      "type": "boolean"
+                    },
+                    "agentId": {
+                      "type": "string"
+                    },
+                    "note": {
+                      "type": "string"
+                    },
+                    "result": {}
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request / validation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Magit unavailable (flag off or no isolation)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "metadataListVersions",
+        "summary": "List saved pack versions for an agent",
+        "description": "Requires METADATA_MAGIT=1 and a durable Mongo connection.",
+        "tags": [
+          "Metadata"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "agentId",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Defaults to first scoped agent id"
+          },
+          {
+            "name": "maxCount",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Version history",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "scope",
+                    "agentId",
+                    "versions"
+                  ],
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "agentId": {
+                      "type": "string"
+                    },
+                    "versions": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Magit unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/metadata/definition": {
       "get": {
         "operationId": "metadataGetDefinition",
@@ -5123,6 +5736,57 @@
         }
       }
     },
+    "/api/intelligence/proposals/{id}": {
+      "get": {
+        "operationId": "intelligenceGetProposal",
+        "summary": "Get one intelligence proposal by id",
+        "description": "Returns the full proposal body from the durable artifact store. Stage via POST /api/metadata/proposals/{id}/stage — never auto-installs.",
+        "tags": ["Intelligence"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Proposal body",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": { "$ref": "#/components/schemas/MemorixScope" },
+                    "proposal": {},
+                    "note": { "type": "string" }
+                  }
+                }
+              }
+            }
+          },
+          "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/intelligence/compare": {
       "post": {
         "operationId": "intelligenceCompare",