@x12i/memorix-service 3.8.0 → 3.10.0

package/dist/openapi/openapi.json

@@ -2218,6 +2218,260 @@
         }
       }
     },
+    "/api/admin/markdown/backfill": {
+      "post": {
+        "operationId": "adminMarkdownBackfill",
+        "summary": "Fill missing _markdown from data on current heads",
+        "description": "Admin repair. Dry-run is the default. Sets source json with generatedFrom data. Skips rows that already have _markdown. Does not change revision, data, or _system.modifiedAt. confirm must be true. includeHistory must stay false.",
+        "tags": ["Admin"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["confirm"],
+                "properties": {
+                  "confirm": { "type": "boolean" },
+                  "dryRun": { "type": "boolean", "default": true },
+                  "includeHistory": { "type": "boolean", "enum": [false] }
+                },
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Backfill counts",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["dryRun", "scanned", "wouldFill", "alreadyPresent", "skippedTooLarge", "skippedInvalid"],
+                  "properties": {
+                    "dryRun": { "type": "boolean" },
+                    "scanned": { "type": "integer" },
+                    "wouldFill": { "type": "integer" },
+                    "alreadyPresent": { "type": "integer" },
+                    "skippedTooLarge": { "type": "integer" },
+                    "skippedInvalid": { "type": "integer" }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "confirm was not true, or includeHistory was requested",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
+              }
+            }
+          },
+          "503": {
+            "description": "Mongo is not connected",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/admin/datasource/backfill": {
+      "post": {
+        "operationId": "adminDatasourceBackfill",
+        "summary": "Stamp _system._datasource on current heads without a content write",
+        "description": "Admin repair. Dry-run is the default. Does not change revision, data, or _system.modifiedAt. confirm must be true. includeHistory must stay false.",
+        "tags": ["Admin"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["confirm", "rules", "unmatched"],
+                "properties": {
+                  "confirm": { "type": "boolean" },
+                  "dryRun": { "type": "boolean", "default": true },
+                  "overwriteBackfill": { "type": "boolean", "default": true },
+                  "includeHistory": { "type": "boolean", "default": false },
+                  "rules": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": ["id", "match", "datasource"],
+                      "properties": {
+                        "id": { "type": "string" },
+                        "match": {
+                          "type": "object",
+                          "properties": {
+                            "orgId": { "type": "string" },
+                            "agentIds": { "type": "array", "items": { "type": "string" } },
+                            "objectType": { "type": "string" },
+                            "contentType": { "type": "string" }
+                          }
+                        },
+                        "datasource": {
+                          "type": "object",
+                          "description": "Do not send basis or recordedAt. Memorix adds basis backfill and recordedAt.",
+                          "required": ["service", "ingress"],
+                          "properties": {
+                            "service": { "type": "string" },
+                            "origin": { "type": "string" },
+                            "channel": { "type": "string" },
+                            "ingress": { "type": "string" }
+                          }
+                        }
+                      }
+                    }
+                  },
+                  "unmatched": {
+                    "type": "object",
+                    "description": "Required. Applied when no rule matches. Do not send basis or recordedAt.",
+                    "required": ["service", "ingress"],
+                    "properties": {
+                      "service": { "type": "string" },
+                      "ingress": { "type": "string" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Backfill counts. dryRun true changes nothing.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["dryRun", "scanned", "wouldStamp", "alreadyStamped", "unattributed", "byRule"],
+                  "properties": {
+                    "dryRun": { "type": "boolean" },
+                    "scanned": { "type": "integer" },
+                    "wouldStamp": { "type": "integer" },
+                    "alreadyStamped": { "type": "integer" },
+                    "unattributed": { "type": "integer" },
+                    "byRule": { "type": "object", "additionalProperties": { "type": "integer" } }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "confirm is not true, includeHistory is true, or the body is invalid",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
+          }
+        }
+      }
+    },
+    "/api/data/datasource": {
+      "post": {
+        "operationId": "dataSetDatasource",
+        "summary": "Set _system._datasource on existing content",
+        "description": "MX-SYS-02. service is x-memorix-caller. Send recordId plus expectedRevision, or filter plus confirm true for one page. datasource may declare origin, channel, originRecordId, originAt, and ingress. Do not send service, basis, or recordedAt.",
+        "tags": ["Data"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["objectType", "contentType"],
+                "properties": {
+                  "objectType": { "type": "string" },
+                  "contentType": { "type": "string" },
+                  "recordId": { "type": "string" },
+                  "expectedRevision": { "type": "integer", "minimum": 1 },
+                  "discriminatorValue": { "type": "string" },
+                  "filter": {},
+                  "confirm": { "type": "boolean" },
+                  "limit": { "type": "integer", "minimum": 1, "maximum": 200 },
+                  "cursor": { "type": "string" },
+                  "datasource": {
+                    "type": "object",
+                    "properties": {
+                      "origin": { "type": "string", "nullable": true },
+                      "channel": { "type": "string", "nullable": true },
+                      "originRecordId": { "type": "string", "nullable": true },
+                      "originAt": { "type": "string", "format": "date-time", "nullable": true },
+                      "ingress": {
+                        "type": "string",
+                        "enum": ["push", "import", "sync", "derive", "migrate", "manual", "replicate"]
+                      },
+                      "sources": { "$ref": "#/components/schemas/DatasourceSourcesDeclaration" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Datasource stamped. Revision increments." },
+          "400": { "description": "Missing target, invalid declaration, or filter without confirm" },
+          "404": { "description": "Record not found" },
+          "409": { "description": "Stale revision" }
+        }
+      }
+    },
+    "/api/data/content/move-fields": {
+      "post": {
+        "operationId": "dataMoveContentFields",
+        "summary": "Move top-level keys between data and _metadata",
+        "description": "data is content. _metadata is producer context and is not rendered into JSON markdown. toMetadata moves keys out of data. toData moves keys back into data. One record, exact revision.",
+        "tags": ["Data"],
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["objectType", "contentType", "recordId", "expectedRevision"],
+                "properties": {
+                  "objectType": { "type": "string" },
+                  "contentType": { "type": "string" },
+                  "recordId": { "type": "string" },
+                  "expectedRevision": { "type": "integer", "minimum": 1 },
+                  "discriminatorValue": { "type": "string" },
+                  "toMetadata": { "type": "array", "items": { "type": "string" } },
+                  "toData": { "type": "array", "items": { "type": "string" } }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Keys moved and revision bumped" },
+          "400": { "description": "Invalid keys, missing source key, or data/metadata conflict" },
+          "409": { "description": "Stale revision" }
+        }
+      }
+    },
     "/api/data/content": {
       "get": {
         "operationId": "dataGetContent",
@@ -2274,6 +2528,14 @@
               "type": "string"
             }
           },
+          {
+            "name": "include",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "JSON object. {\"markdown\":true} returns root _markdown on get and list. Omitted by default. _audit is returned whenever stored and is not part of this flag."
+          },
           {
             "name": "cursor",
             "in": "query",
@@ -2558,6 +2820,22 @@
                   "record": {
                     "$ref": "#/components/schemas/MemorixRecordV2"
                   },
+                  "datasource": {
+                    "description": "Optional document source declaration. Memorix sets service from x-memorix-caller. Do not send service, basis, or recordedAt. record._system._datasource is ignored.",
+                    "type": "object",
+                    "properties": {
+                      "origin": { "type": "string", "nullable": true },
+                      "channel": { "type": "string", "nullable": true },
+                      "originRecordId": { "type": "string", "nullable": true },
+                      "originAt": { "type": "string", "format": "date-time", "nullable": true },
+                      "ingress": {
+                        "type": "string",
+                        "enum": ["push", "import", "sync", "derive", "migrate", "manual", "replicate"]
+                      },
+                      "sources": { "$ref": "#/components/schemas/DatasourceSourcesDeclaration" }
+                    },
+                    "additionalProperties": true
+                  },
                   "precondition": {
                     "$ref": "#/components/schemas/WritePrecondition"
                   },
@@ -13659,91 +13937,684 @@
           }
         }
       }
-    }
-  },
-  "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"
-      },
-      "XMemorixCaller": {
-        "name": "x-memorix-caller",
-        "in": "header",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 128,
-          "pattern": "^[a-zA-Z0-9@][a-zA-Z0-9._@/-]*$"
-        },
-        "description": "MX-CALLER-01: calling application id (e.g. synapix-lander, map-store, memorix-studio, @x12i/memorix-client)",
-        "example": "memorix-studio"
-      }
     },
-    "schemas": {
-      "MemorixScope": {
-        "type": "object",
-        "required": [
-          "orgId",
-          "agentIds"
+    "/api/analytics/counters": {
+      "get": {
+        "operationId": "analyticsCountersList",
+        "summary": "List registered counters (pack analytics[], API registrations, built-ins)",
+        "tags": [
+          "Analytics"
         ],
-        "additionalProperties": false,
-        "properties": {
-          "orgId": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Data universe / org isolation key"
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
           },
-          "agentIds": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "minLength": 1
-            },
-            "minItems": 1,
-            "uniqueItems": true,
-            "description": "Effective metadata agent chain (canonicalized/sorted)"
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
           }
-        },
-        "example": {
-          "orgId": "acme",
-          "agentIds": [
-            "opx",
-            "fieldstone"
-          ]
-        }
-      },
-      "ConnectorCatalogEntry": {
-        "type": "object",
-        "required": [
-          "id",
-          "version",
-          "protocol",
-          "enabled",
-          "framework",
-          "displayName",
-          "capabilities",
-          "isSource",
-          "isTarget",
-          "origin"
+        ],
+        "responses": {
+          "200": {
+            "description": "Counters for the organization",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "items"
+                  ],
+                  "properties": {
+                    "items": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/AnalyticsCounter"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics counters unavailable (no Mongo, or MEMORIX_ANALYTICS=0)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "analyticsCountersRegister",
+        "summary": "Register a counter; results are read from its target record with GET /api/data/content",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "definition"
+                ],
+                "properties": {
+                  "definition": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "description": "An analytics definition (same shape as a pack analytics[] item)"
+                  },
+                  "replace": {
+                    "type": "boolean",
+                    "description": "Rebuild when a counter with this id exists with a different definition"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Accepted; the counter backfills once, then stays current from writes",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "id",
+                    "status",
+                    "counter"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "status": {
+                      "type": "string"
+                    },
+                    "counter": {
+                      "$ref": "#/components/schemas/AnalyticsCounter"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Definition invalid (error.details.issues)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Id taken by a pack or built-in counter, definition differs without replace, or target already used",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics counters unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/analytics/counters/validate": {
+      "post": {
+        "operationId": "analyticsCountersValidate",
+        "summary": "Validate a counter definition without registering it",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "definition": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Validation result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "ok",
+                    "issues"
+                  ],
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "issues": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics counters unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/analytics/counters/{id}": {
+      "get": {
+        "operationId": "analyticsCounterGet",
+        "summary": "Counter status, backfill progress, target address and lastMaterializedAt",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Counter",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AnalyticsCounter"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Counter not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics counters unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "analyticsCounterDelete",
+        "summary": "Unregister an API-registered counter (pack counters are removed from the pack)",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Removed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "removed": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Counter not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Pack or built-in counter",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics counters unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/analytics/counters/{id}/rebuild": {
+      "post": {
+        "operationId": "analyticsCounterRebuild",
+        "summary": "Drop the counter's cells and ledger, then backfill again",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "202": {
+            "description": "Accepted; the counter backfills once, then stays current from writes",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "id",
+                    "status",
+                    "counter"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "status": {
+                      "type": "string"
+                    },
+                    "counter": {
+                      "$ref": "#/components/schemas/AnalyticsCounter"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Counter not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics counters unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/analytics/source-census": {
+      "get": {
+        "operationId": "analyticsSourceCensus",
+        "summary": "Current records by data source (built-in @datasources counter)",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Census",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "ok",
+                    "censusId",
+                    "timestamp",
+                    "status",
+                    "subjects",
+                    "heads"
+                  ],
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "censusId": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "timestamp": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "live",
+                        "backfilling",
+                        "error",
+                        "disabled"
+                      ]
+                    },
+                    "subjects": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "system",
+                          "name",
+                          "total",
+                          "kinds"
+                        ],
+                        "properties": {
+                          "system": {
+                            "type": "string"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "total": {
+                            "type": "integer"
+                          },
+                          "kinds": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "required": [
+                                "kind",
+                                "label",
+                                "count"
+                              ],
+                              "properties": {
+                                "kind": {
+                                  "type": "string"
+                                },
+                                "label": {
+                                  "type": "string"
+                                },
+                                "count": {
+                                  "type": "integer"
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    },
+                    "heads": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "system",
+                          "name",
+                          "total",
+                          "kinds"
+                        ],
+                        "properties": {
+                          "system": {
+                            "type": "string"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "total": {
+                            "type": "integer"
+                          },
+                          "kinds": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "required": [
+                                "kind",
+                                "label",
+                                "count"
+                              ],
+                              "properties": {
+                                "kind": {
+                                  "type": "string"
+                                },
+                                "label": {
+                                  "type": "string"
+                                },
+                                "count": {
+                                  "type": "integer"
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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"
+      },
+      "XMemorixCaller": {
+        "name": "x-memorix-caller",
+        "in": "header",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-zA-Z0-9@][a-zA-Z0-9._@/-]*$"
+        },
+        "description": "MX-CALLER-01: calling application id (e.g. synapix-lander, map-store, memorix-studio, @x12i/memorix-client)",
+        "example": "memorix-studio"
+      }
+    },
+    "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": {
@@ -13992,8 +14863,79 @@
               "provenance": {
                 "type": "object",
                 "additionalProperties": true
+              },
+              "_datasource": {
+                "$ref": "#/components/schemas/DatasourceStamp"
               }
             }
+          },
+          "_markdown": {
+            "$ref": "#/components/schemas/RecordMarkdown"
+          },
+          "_audit": {
+            "type": "object",
+            "description": "Optional audit of this record, not of its content and not _markdown.metadata. Returned on get, list, and query whenever stored. Not an include flag. Not rendered into JSON markdown. provider, model, and reasoningEffort are required when the object is present. Other keys stay open, including verdict.",
+            "required": ["provider", "model", "reasoningEffort"],
+            "properties": {
+              "provider": { "type": "string", "minLength": 1 },
+              "model": { "type": "string", "minLength": 1 },
+              "reasoningEffort": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": true
+          }
+        }
+      },
+      "RecordMarkdown": {
+        "type": "object",
+        "description": "Original text beside data. Omitted from get and list unless the include query asks for markdown. Clients may send source ai or content. source json is filled by Memorix from data.",
+        "required": ["content", "source"],
+        "properties": {
+          "content": { "type": "string" },
+          "source": { "type": "string", "enum": ["ai", "json", "content"] },
+          "metadata": { "type": "object", "additionalProperties": true }
+        },
+        "additionalProperties": true
+      },
+      "DatasourceStamp": {
+        "type": "object",
+        "description": "Memorix-owned document source. Not part of data. Absent on records written before MX-SYS-02.",
+        "required": ["service", "ingress", "basis", "recordedAt"],
+        "properties": {
+          "service": { "type": "string" },
+          "ingress": {
+            "type": "string",
+            "enum": ["push", "import", "sync", "derive", "migrate", "manual", "replicate", "unknown"]
+          },
+          "basis": {
+            "type": "string",
+            "enum": ["declared", "caller", "preserved", "backfill"]
+          },
+          "recordedAt": { "type": "string", "format": "date-time" },
+          "origin": { "type": "string" },
+          "channel": { "type": "string" },
+          "originRecordId": { "type": "string" },
+          "originAt": { "type": "string", "format": "date-time" },
+          "sources": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["system", "name"],
+              "properties": { "system": { "type": "string" }, "name": { "type": "string" } }
+            }
+          }
+        }
+      },
+      "DatasourceSourcesDeclaration": {
+        "description": "Connector the record came from; the census and @datasource groups file it under sources[0]. Replaces stored sources; null or [] clears them; omit to keep them.",
+        "type": "array",
+        "nullable": true,
+        "maxItems": 8,
+        "items": {
+          "type": "object",
+          "required": ["system", "name"],
+          "properties": {
+            "system": { "type": "string", "pattern": "^[a-zA-Z0-9@][a-zA-Z0-9._@/-]*$", "maxLength": 128 },
+            "name": { "type": "string", "minLength": 1, "maxLength": 128 }
           }
         }
       },
@@ -15931,6 +16873,134 @@
             }
           }
         }
+      },
+      "AnalyticsCounter": {
+        "type": "object",
+        "required": [
+          "id",
+          "origin",
+          "status",
+          "generation",
+          "target",
+          "backfill"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "origin": {
+            "type": "string",
+            "enum": [
+              "pack",
+              "api",
+              "builtin"
+            ]
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "backfilling",
+              "live",
+              "error"
+            ]
+          },
+          "generation": {
+            "type": "integer"
+          },
+          "hash": {
+            "type": "string"
+          },
+          "agentIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "target": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "properties": {
+              "objectType": {
+                "type": "string"
+              },
+              "contentType": {
+                "type": "string"
+              },
+              "recordId": {
+                "type": "string"
+              }
+            }
+          },
+          "history": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": true
+          },
+          "backfill": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "cursor": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "done": {
+                  "type": "boolean"
+                },
+                "seen": {
+                  "type": "integer"
+                }
+              }
+            }
+          },
+          "registeredAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "registeredBy": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "liveAt": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date-time"
+          },
+          "lastMaterializedAt": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date-time"
+          },
+          "error": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
       }
     }
   }